Forem: Zac Jiang

Become the software engineer with strong fundamentals.

Zac Jiang — Wed, 09 Aug 2023 06:10:56 +0000

In the ever-changing world of software engineering, it is tempting for developers to focus on the latest trends and technologies. While staying up to date is essential; it is equally crucial to recognize the significance of mastering the fundamentals. Fundamentals act as the backbone of a developer's skill set. This article delves into some of these important concepts and highlights how a strong foundation can lead to long-term success in the field of software engineering.

The ever-changing landscape

Technology evolves extremely rapidly, and software developers often encounter new frameworks and languages throughout their careers. A firm grasp of fundamentals equips developers with the adaptability needed to learn these new technologies quickly when needed.

Instead of being confined to a particular language or framework, developers who understand the underlying principles of programming can transition smoothly to new technologies. This adaptability is critical in an industry where innovation is constant.

Take Frontend development as an example. Frontend developers witness a continuous influx of new frameworks year after year. And different organisations will adopt different frameworks. Now, if you are a developer who wants to be "ahead of the curve", you could upskill on the new shiny framework/s so you are prepared to work for any organization. I used to have this mindset; and let me tell you, it is a waste of time. Because for most people, when something is learnt but not applied, it will be forgotten. What you should focus on is understanding the fundamentals of Frontend development. Additionally, go beyond the surface and dive deep into how the internals work and understand how UI elements are rendered onto a web page, how javascript interacts with the UI, how to handle API calls etc...

By focusing on strong fundamentals, you will be able to jump from one framework to another. It is not too difficult for a React developer to jump to using Vue if that developer has a strong understanding of HTML, CSS and JS, state management, responsive web design etc... For example, recently, I had to take over an Angular project. Now, I have never worked with Angular prior; throughout my career, I have only worked with React. Nonetheless, I took over the code base and I was able to be productive fairly quickly due to my years of experience in the Frontend space.

Develop strong problem-solving skills

At the core of software development lies the ability to solve problems. Strong problem-solving skills and the ability to debug are invaluable. Understanding fundamental principles in programming allows developers to pinpoint issues quickly, saving time and resources.

Become the developer who exudes confidence in their problem-solving skills. This assurance empowers individuals to embrace new challenges and take on greater responsibilities. Moreover, developers who prioritize mastering problem-solving often find themselves sought after by employers who recognize the immense value they would provide for an organisation.

When I encounter a problem, I usually go through the following steps to solve it:

REALLY understand the problem and the desired outcome.
Discover unknowns and potential effects.
Explore all solutions and the potential drawbacks of each solution.
Select the best solution and implement it.

Note: I intentionally wrote the steps to be quite vague as these steps are not only for solving coding problems but also for all problems software engineers encounter daily.

As final words of wisdom on this topic; be the person who can solve difficult problems.

The technicals

And finally, we get to the technicals. I had intentionally left this part to the end because I wanted to put more emphasis on the importance of the previous 2 points. Nonetheless, even though this is the last point, it does NOT make it less important.

Below is a list of some of the technicals that a developer should master:

Data structures and algorithms: These are the building blocks of software. Data structures store and organize data, while algorithms are used to process that data. A good understanding of data structures and algorithms is essential for writing effective and efficient code.
Object-oriented programming: This is a popular programming paradigm that allows developers to create reusable and maintainable code. Object-oriented programming is based on the concept of objects, which are self-contained units of code that encapsulate data and behaviour.
Software design and architecture: This is the process of planning and designing software systems. A good software design will ensure that the system is well-organized, scalable, and easy to maintain.
Testing and debugging: Closely related to the "Develop strong problem-solving skills" section, these are essential activities for ensuring the quality of software. Testing is the process of executing software to find errors, while debugging is the process of fixing those errors.

The above list is just a few of the technicals a developer should master, but do consider other technicals if the domain requires it, i.e. mastering CSS-animation.

In conclusion, the importance of fundamentals in software development cannot be overstated. While keeping up with the latest technologies and trends is essential; a solid understanding of core principles and concepts provides the foundation for success.

How to keep your code elegant, readable and maintainable

Zac Jiang — Fri, 21 Jul 2023 08:37:24 +0000

In the world of software development, simplicity and elegance are highly valued qualities in code. Writing elegant code requires thoughtful design and attention to detail. In this article, we will explore some key principles and practices for achieving this.

Note, before we go on, I do understand that larger organisations have their own internal guidelines for writing clean code. If you're one of those individuals who work for one of those organisations, you should know that this article is not a replacement for those guidelines but rather a general idea of how a clean code base should be written.

Here is a list of all the points we will be discussing in this article:

Use Descriptive Names
Keep Functions and Methods Small and Focused
Avoid nested if statements
Avoid undescriptive chaining conditions in if statements
Write Readable and Self-Documenting Code
Eliminate Code Duplication (kinda)
Properly structure the project directories
Write Unit Tests

Use Descriptive Names: Choosing clear and descriptive names for variables, functions, and classes is essential for writing elegant code. Names should accurately reflect the purpose and functionality of variables and functions. Avoid cryptic abbreviations or acronyms that may confuse other developers. Intention-revealing names make the code self-explanatory and reduce the need for comments. For an in-depth discussion, guidelines and examples on variable naming, read my article The art of naming variables

Keep Functions and Methods Small and Focused: One of the fundamental principles of writing simple and elegant code is to keep functions and methods small and focused. Aim for functions that perform a single task and have a clear purpose. Breaking down complex logic into smaller, more manageable pieces. Below is an example of taking user input and running a sorting algorithm:

def sort_array(arr):
    if arr:
        if len(arr) > 1:
            algorithm = input("Enter the sorting algorithm (bubble, insertion, quick): ")
            match algorithm:
                case "bubble":
                    # bubble sort logic
                case "insertion":
                    # insertion sort logic
                case "quick":
                    # quick sort logic
                case _:
                    print("Invalid sorting algorithm.")
        else:
            print("The array has only one element.")
    else:
        print("The array is empty.")

Although the above does work, it's doing too many things, such as array validation, getting user input, writing out each sorting logic inside each of the switch cases and using string values for each switch case. All these things make the function complex and difficult to debug. Instead, we should break down this larger function into smaller ones where each function will have its own responsibility:

class SortEnum(Enum):
    BUBBLE = "bubble"
    INSERTION = "insertion"
    QUICK = "quick"

def bubble_sort(arr):
    # Bubble sort implementation
    pass

def insertion_sort(arr):
    # Insertion sort implementation
    pass

def quick_sort(arr):
    # Quicksort implementation
    pass

def validate_array(arr):
    if not arr:
        print("The array is empty.")
        return False
    if len(arr) <= 1:
        print("The array has only one element.")
        return False
    return True

def get_sorting_algorithm():
    algorithm = input("Enter the sorting algorithm (bubble, insertion, quick): ")
    return algorithm

def sort_array(arr):
    if validate_array(arr):
        algorithm = get_sorting_algorithm()
        match algorithm:
            case SortEnum.BUBBLE:
                bubble_sort(arr)
            case SortEnum.INSERTION:
                insertion_sort(arr)
            case SortEnum.QUICK:
                quick_sort(arr)
            case _:
                print("Invalid sorting algorithm.")

Although separating the function into multiple functions like this increases the number of lines of code. However, it is now much easier to extend functionality and debug any issues that may arise in the future.

Note that in a real code base, the enum class and some of the functions should be in different files.

Avoid nested if statements: Nested if statements can quickly lead to code complexity, making it harder to understand the logic flow and increasing the chances of introducing bugs during development or future modifications. As the number of nested if statements increases, the code becomes more convoluted, and it becomes difficult to track which condition corresponds to which block of code; this is especially true for languages such as Python that rely on indentations. This can lead to a phenomenon known as the "arrowhead anti-pattern," where code branches out into an arrowhead shape, making it challenging to follow the program's logic. For example, Suppose you are developing a software application that processes customer orders. You want to validate the order before processing it. Here's an example of deeply nested if statements:

def process_order(order):
    if order.is_valid():
        if order.has_sufficient_inventory():
            if order.has_valid_payment():
                order.process()
            else:
                print("Invalid payment")
        else:
            print("Insufficient inventory")
    else:
        print("Invalid order")

In this example, as the validation steps increase or become more complex, the logic can be very hard to follow. A better approach is to use a guard clause or early exit strategy to avoid excessive nesting. Here's an improved version using guard clauses:

def process_order(order):
    if not order.is_valid():
        print("Invalid order")
        return

    if not order.has_sufficient_inventory():
        print("Insufficient inventory")
        return

    if not order.has_valid_payment():
        print("Invalid payment")
        return

    order.process()

Avoid undescriptive chaining conditions in if statements: When conditions are chained together with logical operators such as and or or, the code can quickly become difficult to comprehend. The below example needs to do 3 checks before the user can edit it:

# check user can edit
if user.role == RoleEnum.ADMIN and 
   job.status == JobStatusEnum.OPEN and 
   job.type == JobTypeEnum.CONTRACT:
        pass

The above is what is typically seen in a code base, although there is a comment telling the reader what this check is for, we can instead assign a variable to the condition:

can_edit = user.role == RoleEnum.ADMIN and 
   job.status == JobStatusEnum.OPEN and 
   job.type == JobTypeEnum.CONTRACT

if can_edit:
    pass

This makes the code much easier to comprehend at a glance.

Write Readable and Self-Documenting Code: Strive to write code that is self-explanatory and easy to understand by implementing the above points. Well-designed code should read like a narrative, making the logic and flow clear to other developers without the use of comments. Use consistent formatting, indentation, and spacing to enhance readability. In saying this, do use comments where needed, such as classes or functions that require domain knowledge.

Eliminate Code Duplication (kinda): Code duplication not only increases the chances of errors but also makes code harder to read and maintain. Eliminating duplication through code reuse and abstractions. Identify repeated patterns or functionality and extract them into reusable functions, modules, or classes. What I am referring to here is the "Don't repeat yourself" (DRY) principle. But one does need to understand how to use DRY properly rather than using it everywhere. Hence the "Avoid hasty abstraction" (AHA) programming principle is gaining popularity. It remains the developers that it is ok to not DRY everything in the codebase, but rather use DRY where appropriate; this article summarises this principle.

Properly structure the project directories: A well-designed project directory provides several benefits. Firstly, it improves code maintainability by creating a logical separation of different modules. Secondly, a clear folder fosters a better understanding of the project's architecture and reduces the risk of code duplication. Team members can quickly find what they need and grasp the project's overall layout. Lastly, a structured folder hierarchy simplifies version control management, as it allows developers to track changes systematically. For a deeper discussion and examples of folder structures, have a read of my articles, Express.js: The dangers of unopinionated frameworks and best practices for building web applications and Here is how you write scalable and maintainable React components for projects of any size.

Write Unit Tests: Unit testing is a very important part of the software development lifecycle. Writing tests not only verify the correctness of the code but also act as living documentation and provide confidence during refactoring or modifying code. It is important that we not only test the "happy" path but more importantly, the "un-happy" scenarios. We as developers are usually very lenient when it comes to testing, so we need to test all scenarios the users could face. But in saying this, there is a balance to writing the appropriate amount of tests, you don't want to overdo it as this will result in increased dev time for writing and maintaining the tests.

In conclusion, writing simple and elegant code is a goal worth pursuing in software development. By embracing these principles and strive for simplicity and elegance in your codebase to reap the long-term benefits.

The Art of Naming Variables: Avoiding ambiguity and promoting clarity

Zac Jiang — Sat, 15 Jul 2023 02:37:28 +0000

In the world of programming and software development, variables serve as the building blocks for creating functional applications. They allow us to store and manipulate data, making our programs dynamic and interactive. However, the art of naming variables is often overlooked or underestimated, leading to code that is difficult to understand. By choosing unambiguous variable names, developers can greatly enhance the readability and maintainability of their code.

In this article, we will explore the importance of naming variables and provide some best practices to promote clarity. And although this article is more targeted towards junior and intermediate developers, it also serves as a reminder to more experienced devs on the importance of proper variable names.

1) Use descriptive names: One of the fundamental principles in variable naming is to choose names that accurately reflect the purpose or content of the variable. Instead of using generic names, opt for more descriptive and meaningful names that convey the intent of the variable. For example:

2) Avoid Abbreviations and Acronyms: While abbreviations and acronyms might seem like a convenient way to shorten variable names, they can often introduce ambiguity and confusion. Not everyone will be familiar with the same abbreviations, and different team members may interpret them differently. Instead, favour descriptive names that provide clarity and reduce the chances of misinterpretation. This is especially true for any developers coming into a new industry without prior domain knowledge. For example:

There are instances where common abbreviations can be used, these are usually very commonly used among developers, such as:

3) Naming variables to indicate the data type: When naming variables, it is important the name indicates the data type. This is so that when another developer reads a variable, they instantly know what data type it is and what it's used for. For example, boolean variables should start with is, has or can. And similarly, singular and plural also need to be considered when choosing variable names. This indicates whether the variable represents a single element such as a string, or number or multiple elements such as an array. Examples:

4) Be Mindful of Scope: The scope of a variable determines its visibility and lifespan within a program. When naming variables, it is essential to choose names that accurately reflect their scope. Variables with global scope, accessible throughout the program, should have names that indicate their broader purpose or functionality. On the other hand, variables with limited scope, such as local variables within a function or loop, can have more concise and specific names that reflect their immediate purpose. For example:

5) Be Consistent: Lastly, consistency is key in variable naming and is crucial for maintaining code readability and reducing confusion. Establish a set of naming conventions or guidelines and stick to them consistently throughout your codebase. This could include rules such as using camel case (e.g., firstName) or underscores (e.g., first_name). Consistency extends beyond projects and should be applied across the organization to ensure seamless collaboration and code maintenance among all developers.

In conclusion, the art of naming variables is an essential skill for any developer. By following these best practices and guidelines, developers can create code that is easier to understand and maintain. Clear and descriptive variable names improve the readability of code, make it more accessible to other developers, and save valuable time during the development and maintenance phases. So, let's embrace the art of naming variables and elevate the quality of our code.

Challenging the daily Stand-Up: Debunking the need for daily meetings in Scrum

Zac Jiang — Wed, 28 Jun 2023 09:50:29 +0000

In today's rapidly evolving business landscape, organizations are seeking strategies that enable them to swiftly adapt and thrive. Agile methodology has emerged as a powerful framework that fosters flexibility, collaboration, and innovation.

Scrum, a widely adopted agile framework, emphasises frequent communication and collaboration. However, one aspect of Scrum, the daily stand-up meeting, has sparked debates among practitioners. In this article, I will delve into the reasons why stand-ups are not necessary for Scrum and explore alternative approaches that deliver the same value while wasting less time and energy.

Why a daily standup?

"The daily stand-up meeting enables teams to synchronize their efforts, align their goals, and plan their activities for the day. By providing a dedicated time for all team members to share updates on their progress, challenges, and plans, the stand-up ensures that everyone is aware of the team's collective achievements and potential roadblocks." - ChatGPT

The above statement is from when I asked ChatGPT: "What is the reason for a daily stand-up in Agile Scrum?". That is something I used to believe is true. However, the further I am into my career as a Software Engineer, I now have a different point of view (POV) regarding stand-ups; and that POV is that stand-ups should be eliminated in Agile Scrum. They are more of a nuisance rather than value-adding.

Below is a list of points why I believe the daily stand-up brings a lot more drawbacks than the value it is perceived to provide.

Time efficiency and value

Stand-up meetings are time-consuming and unproductive. With team members providing status updates daily, the meetings can become repetitive, especially when there are minimal changes from the previous day. This redundancy leads to wasted time that could be better utilized for actual work. Instead, information sharing and coordination can be achieved through other channels, such as digital project management tools or asynchronous communication platforms, where team members can provide updates and address queries without the need for a daily physical or virtual gathering.

By eliminating the daily meeting, teams can allocate more time and energy towards the actual delivery of valuable increments and concentrate on the tasks at hand. By reducing interruptions, and maintaining a steady flow of progress, ultimately leading to improved productivity and timely delivery.

Stand-up meetings are (usually) NOT stand-up meeting

Stand-up meetings can sometimes become lengthy and eat into valuable work time, particularly if they are not well-structured or if team members provide excessive details and discussions on a particular topic or issue. If the meeting runs for an extended period, it can result in reduced productivity and hinder progress on actual tasks. Oftentimes, team members forget the meeting is a stand-up, and go on to discuss technical and/or business requirements. This, in turn, defeats the purpose of a stand-up which is to only update the team on 3 points, these are: What I did yesterday, what I am doing today, and any blockers. Those 3 points can be a simple message on dedicated channels.

Not adapting to Context and team dynamics

Scrum emphasises flexibility and different teams may have unique dynamics and needs. The rigid adherence to a daily stand-up meeting may not be suitable or effective for all situations. Some teams may work in remote or distributed setups, making daily stand-ups impractical. Others may have naturally high levels of collaboration and communication, rendering the daily meeting redundant. Instead, teams can adapt their communication practices based on their specific context, choosing alternative methods that better suit their dynamics while still maintaining transparency and alignment. This is especially true for team members working in completely different time zones. It can be extremely difficult to find a time slot where all participating members can attend, and in turn, will receive minimum value in exchange.

Can feel like micro-managing

The daily stand-up, with its emphasis on individual status reporting, can inadvertently create a micro-managing culture within teams. By removing the stand-up, teams can shift towards a more trusting and empowering environment, allowing individuals to take ownership of their work and collaborate more freely. Trusting team members to communicate their progress and seek assistance when needed fosters a sense of autonomy, accountability, and self-organisation within the team.

Repetitive and disengaged

If the stand-up meeting becomes monotonous or lacks active participation, team members may disengage mentally, leading to reduced focus and meaningful contribution. This is especially true when team members that are not required to be there, or are not currently actively working on the project waste their time sitting in a stand-up meeting with no value added or received.

If the sprint planning sessions are done properly, each team member would all know what they're doing, and what is next once a ticket is completed.

But have no fear, replacing the stand-up is near, if your team implements the following

Asynchronous Communication: Teams can leverage digital communication tools, such as project management software to help track progress, instant messaging platforms, or collaboration tools, to facilitate ongoing communication. Team members can provide updates, share progress, and address any impediments asynchronously. This allows for flexibility in timing and allows team members to communicate at their convenience while still maintaining transparency.
Daily Progress Updates: Instead of a formal daily stand-up meeting, teams can provide daily progress updates through a shared document or communication channel. Each team member can summarise their accomplishments, ongoing tasks, and any challenges they may be facing. This approach ensures that everyone is aware of the team's progress and can identify potential areas of collaboration or assistance.
Sprint Planning Sessions: Teams can dedicate more time to do proper sprint planning sessions to discuss priorities, tasks, and potential challenges. By thoroughly discussing and aligning on the upcoming work, teams can set clear goals and establish a shared understanding of the tasks at hand. This allows for a collaborative approach to planning and ensures that everyone is on the same page regarding project objectives and expectations. Delegating tickets for a team member to fill a sprint makes the daily stand-up redundant.
Ad hoc Meetings: Instead of a daily stand-up, teams can schedule ad hoc meetings as needed. These meetings can be focused on addressing specific issues, clarifying requirements, or conducting in-depth discussions. By utilising targeted meetings, teams can maintain a proactive approach to problem-solving and ensure that important topics are addressed promptly without the need for a daily meeting.

Given the drawbacks listed above and the solutions, we can eliminate the stand-up and focus our time on what really matters such as delivering software, fixing bugs, writing good documentation and many more things that bring tremendously more value to the business than a daily stand-up.

Documentation is Essential in Software Engineering and we all need to write more of it.

Zac Jiang — Fri, 23 Jun 2023 06:16:54 +0000

Introduction

In the world of software engineering, documentation plays a vital role in ensuring the success of projects. It provides a comprehensive understanding of the software system, its components, and its functionality. While some developers might consider documentation as an unnecessary burden, it is, in fact, a critical aspect of the software development process. While many companies have well-written user guides for their users, internal documentation is just as important. My goal for this article is to inspire developers and other team members - Product Owners, Quality Assurance, Project Managers etc... to make documentation part of their BAU.

Knowledge transfer

Firstly, let's talk about the most important aspect of documenting software, and that is knowledge transfer. Knowledge transfer is essential for maintaining business continuity and ensuring that the software continues to evolve and meet the changing needs of users. Additionally, comprehensive documentation helps new team members or external contributors to quickly familiarize themselves with the software, reducing the onboarding time and facilitating a smoother transition. It will also provide domain knowledge to new devs who have not worked in that particular domain i.e.: law, finance, aviation etc...

Documentation ensures the transfer of knowledge from one generation of developers to the next. When a software project is handed over from one team to another, or from one organization to another, documentation becomes a crucial asset. It provides insights into the design choices, implementation details, and overall project context. Properly documented projects eliminate the need for reverse engineering or spending excessive time deciphering the existing codebase. In my personal experience, one of the most frustrating things I have had to deal with is taking over a poorly written piece of software that was acquired externally. This particular piece of software had many architectural design flaws. And of course, very poorly documented. It took our team a tremendous amount of time to dig through the maze-like architecture. Not only this but trying to fix bugs and adding features took substantially longer and fixes were released to production without much confidence.

Good habits take time to build

Most (if not all) of us start our careers as junior developers. Junior developers often find themselves immersed in coding tasks and eager to make their mark in the field. And the last thing any developer starting out in this field would think about is writing documentation. I, in particular, thought this is a job for senior devs. At least that was my thinking when I got my first dev job. But now looking back, I realised that was a mistake on my part and I should've developed a habit to contribute to the documentation.

When junior developers actively contribute to documentation, they gain a deep understanding of the project's architecture, requirements, and design decisions. This process allows them to comprehend the bigger picture and aids in developing a solid foundation of knowledge. By immersing themselves in the documentation, they will gain insights into best practices, coding conventions, and project standards, enhancing their ability to write clean, maintainable code.

Documentation offers an opportunity for junior developers to analyze and articulate complex problems and their solutions. By documenting their thought processes, they refine their problem-solving skills and enhance their ability to explain technical concepts effectively. Through the act of documenting, junior developers gain a deeper understanding of the challenges they face, the solutions they implement, and the reasoning behind their decisions. This skill development not only benefits the immediate project but also lays a strong foundation for their professional growth in the long run.

Documentation is everyone's responsibility - not just the developer's

Documentation facilitates collaboration among team members. In software development projects, teams often consist of multiple individuals working together to achieve a common goal. Documentation serves as a means of communication, allowing team members to share their ideas, insights, and progress with their colleagues.

I have been rambling on and on about documentation, but mostly from a developer's perspective, but the responsibility should be with everyone who works on the project. By documenting the project's business requirements, architecture, design decisions, and implementation details, team members can understand the system as a whole and work together more efficiently. It serves as a reference point that promotes shared knowledge and understanding among team members, ensuring that everyone is on the same page. Moreover, contributing to documentation ensures that knowledge is not locked inside the heads of specific individuals, preventing the risk of information loss when team members leave or move on to other projects.

To hammer on this point, everyone should contribute to documentation as knowledge is widespread among the team. As a piece of software grows in complexity, the team can easily look up relevant information in the documentation instead of doing what I would call "doing it the corporate way" of setting up a meeting, making sure the required people are available, recording the meeting etc... A more hassle-free approach is to point someone to the documentation for the knowledge.

Final thoughts

As developers, we generally think our job is to write code and debug problems. Although this is true, we also need to consider the other aspect of Software Engineering, and that is writing documentation that will be a reference point for other team members. I hope I have inspired my readers and make writing documentation a part of their BAU.

Hiring offshore developers can save a company a lot of money, so why don't they?

Zac Jiang — Sun, 18 Jun 2023 03:19:45 +0000

Introduction

In today's globalised world plus the advancements of the Internet and technology as a whole, hiring software engineers from developing countries seem to be an ideal strategy from a financial point of view to cut costs and a potential boost in productivity. The typical Senior Software Engineer salary in Australia is $94,000 USD p.a. 1 and $85,000 USD p.a. in New Zealand 2. Compared to the average salary for an engineer in India ($14,000 USD 3) or Pakistan ($16,600 USD 4). But the question is, why don't we see companies hiring more offshore developers? I am not referring to companies that have offshore bases already set up such as Microsoft. I am referring to small to medium-sized companies that don't have a presence in developing countries.

While there are certain advantages to this approach, I have come to realise the potential drawbacks it poses for companies. In this article, I will share my personal experience, plus experiences from dev managers and engineering leads to shed light on why we think hiring offshore software developers does benefit the business from a financial point of view, but in practice, it is very different.

Communication challenges and understanding of the product and/or concept

One of the most significant hurdles I faced when working with offshore developers was communication challenges that often led to misunderstandings and misinterpretations. This resulted in delays, inefficiencies, and increased project management overhead. Effective collaboration and clear communication are crucial in software development, and communication challenges pose a significant obstacle to achieving those goals.

A most recent example where I experienced a misunderstanding in communication was working with a QA from offshore. I had been working on a security fix. The ticket clearly states this is a security fix and which endpoint needs to be tested. When it was time for testing, the QA tested another endpoint instead. To remedy this, I had to get on a call with him to re-explain that issue, the fix and which part of the application requires testing. Although this is a minor misunderstanding, it does lead to time-wasting and having to re-explain the concept. If this was something more serious, it can be detrimental. Although this experience was referring to a QA, I have had similar experiences with developers where the lack of understanding led to wasted time and effort.

Quality Control

Ensuring high-quality standards in software development is paramount. However, when working with offshore developers, maintaining consistent quality became a considerable challenge. It was difficult to assess the skills, expertise and their way of logical thinking (in a coding context). This lack of visibility into their capabilities resulted in inconsistent code quality and an increased risk of introducing bugs or technical debt into the project. It became evident that maintaining quality control was a constant concern when working with offshore teams.

Another area of issue is that some of the offshore developers come from a culture of "people pleasers". And by that I mean, they are essentially "yes men". They usually wouldn't ask clarifying questions even though they have not fully understood the business requirements. I understand this fully as I also come from a culture of people pleasers. It might sound nice to have a developer say "yes" all the time, but it is extremely frustrating when the "yes" is not a confident yes, but rather it's a "yes" that pleases the product owners. This has led to many headaches for me in the past as I had developers who is always saying yes to the tickets I assign to them, but in the end, they did not understand what was asked and resulted in delays and incorrect solutions to the problem.

Lack of Cultural Alignment

Although we, as developers got into this industry because we love to deal with computers rather than people. Software development is a collaborative process that thrives on effective teamwork and cultural alignment. However, many offshore developers often lack familiarity with the company's culture, work processes and business goals. This lack of cultural alignment hindered collaboration, and innovation and resulted in misunderstandings or conflicting expectations. The absence of a shared work culture created a barrier to building a cohesive and productive team.

Given offshore developers are "offshore", we are only able to "get to know them" over video calls. Now, there is nothing wrong with trying to collaborate over video calls, but the interactions should not only be about the problem or work at hand. In Australia and New Zealand, we are accustomed to having informal "chit-chat" before and/or after a meeting. I have tried numerous times to strike up conversations with my offshore colleagues and the response is usually one-word answers. Now, this may be due to language barriers or cultural differences, but this does hinder relationship-building with your colleagues.

It is important for me to point out that the working style of my offshore colleagues might work best in their respective countries. This article was not to criticise offshore developers but rather to highlight the differences in the way we work and the risks involved when hiring from offshore.

Conclusion

Hiring offshore software developers may present certain advantages initially but it also comes with inherent risks and drawbacks. Communication challenges, quality control issues and cultural misalignment all impact the success of a software application.

Express.js: The dangers of unopinionated frameworks and best practices for building web applications.

Zac Jiang — Tue, 13 Jun 2023 07:50:27 +0000

Introduction

Express.js is a popular Node.js web application framework that is well-known for its minimalist and unopinionated nature. While its flexibility and simplicity appeal to many developers, there are inherent risks and drawbacks associated with this. In this article, we will explore the downsides of Express.js due to its unopinionated nature and discuss the best practices for building robust, maintainable and scalable applications.

Issues with an unopinionated framework

Express.js offers developers a high level of freedom and customization, allowing them to choose from a vast ecosystem of middleware, plugins, and approaches. However, this freedom comes at a cost, as the absence of defined conventions and best practices can lead to inconsistent codebases. I have seen many Express.js code bases during my career, and some of these codes are PAINFUL to look at, to say the least. Some of these bad practices include; no separation of concern (controller, service and repository code all in one file), not using Typescript, no API documentation etc...

Without a clear structure, developers have free rain to architect an application however they choose leading to codebases that are difficult to navigate and understand. This can hinder collaboration, increase maintenance overhead, and make it harder for new team members to on board. As an application grows and evolves, maintaining an Express.js codebase becomes increasingly challenging. As mentioned, without proper separation of concern, refactoring or extending existing functionality can be complex and prone to errors. This can result in technical debt and hinder the ability to adapt to changing business requirements.

Best Practices for Building an Express.js App

While Express.js has its drawbacks, it is still one of the most popular (and most recommended) frameworks out there for writing Node.js applications due to its minimalist approach and ease of use 1 2. Below are methods/techniques that will lead to the success of writing a well-engineered Express.js application.

Well-defined project structure

The essence of building a well-written Express.js app is to establish a clear project structure which is crucial to maintain code readability and scalability. Consider using the ever-so-popular "separation of concern" pattern to organize your codebase effectively.

In my experience, there are 2 ways that Express.js projects should be structured; these are:

Option 1: Create directories for each layer of the application; controllers, services, and repository. Inside each directory, create sub-directories for each class.

- src
   - controllers // responsible for handling HTTP requests
       - client
            client.controller.ts
            client.schema.ts
            client.dto.ts
   - services // responsible for business logic 
       - client
            client.service.ts
   - repository // responsible for querying databases and/or calling other services
       - client        
            client.model.ts // this is the model for the ORM

Option 2: Create a directory for each class, and inside, create all the files related to the class.

- src
    - client
        client.controller.ts
        client.service.ts
        client.model.ts  
        client.schema.ts
        client.dto.ts

As we can see in the above, there is a clear separation of concern for each layer of the application. This allows the application to grow and be easily maintained.

Typescript everything

A colleague once said to me: "Javascript is a terrible language, Typescript makes it bearable". And needless to say, he is 100% correct. There are numerous articles stating why we should use Typescript instead of plain Javascript; here are just a few with a simple Google search: 3 4 5. But just to list a few advantages of Typescript, these are; enhanced productivity, maintainability and scalability, improved code documentation and much, much more. But what still surprises me is that despite all these benefits, I still see applications written in plain Javascript. This is not limited to Express.js code bases; I see the use of Javascript in a lot of applications.

And my final thoughts on this point; TYPESCRIPT EVERYTHING!!!

Document the application

From my experience, I noticed developers have a strong dislike for writing documentation; this is true even for senior developers. I hold the strong opinion that documentation is almost just as important as the app itself. And the benefits include easy onboarding, easy handover, for customers if the app is being sold, and so on.

But the question is, why isn't this done more in practice? I think I know the reason, and that is; most devs have this mindset they are only writing code for themselves and do NOT think about how it will impact the next person working on the app. I am also guilty of this in the past. But I have learnt from my mistakes and have implemented several simple ways to write API documentation; these include Swagger documentation, Postman collections, a simple confluence space or a combination of the 3.

Proper documentation makes everyone's lives easier. My only hope is that this article inspires the next developer to take writing documentation part of their daily task.

Conclusion

While Express.js's unopinionated nature provides developers with flexibility and freedom, it comes with inherent risks and challenges. By understanding these downsides and adopting best practices, developers can mitigate potential pitfalls and build robust and maintainable Express.js applications.

Here is how you write scalable and maintainable React components for projects of any size.

Zac Jiang — Fri, 09 Jun 2023 03:14:31 +0000

We all know React is a library and not a framework, and that, unfortunately, is it's biggest drawback.

Compared to the other 2 popular frontend frameworks out there; Angular and Vue, React really is the odd child.

I wholeheartedly believe that we all should be using frameworks rather than libraries to create SPA (single-page applications); as it gives structure to the code base. The reason why React is the most popular of the 3 is that it is a library, and developers can "whip" something up quickly without following the strict guidelines of a framework. This is one of the main reasons why it propelled React to the top of the popularity scale.

Open positions for React, Angular and Vue developers for October 2018. Ref 1

But just because something is popular, doesn't mean it is the best. Given that it is an unopinionated library, developers have free rain on how they structure their code base; or not structure it at all. This isn't a good thing majority of the time, especially for larger projects. I have seen a lot of crazy React code in my time, and let me tell you, it is CRAZY. I have worked with code bases that are one index.js file long. And other instances where all the components for one page is in one file.

We all have heard the phrase "React is good for small to medium size projects, but for larger projects, use Angular". Although there are truths to this, I believe React can be good for larger projects if it is structured properly.

Throughout my career, I have undoubtedly found the best way to write React; I call this the "Smart container, dumb component" method of writing React components. This method allows the project to scale and is easily maintainable.

Here is how this works; if we want to render the user list to the screen, we would create a dumb component (dumb components re-render on prop or state change) called UserList.ts which is only responsible for displaying the user list plus the loading and error states.

const UserList = ({isLoading, hasError, userList}:props) => {
  return jsx
}

Then, we would create another file called UserListContainer.ts which will be our container component where all business logic resides. Such as making API requests, data manipulation and passing state to the dumb component.

const UserListContainer = () => {
// make API request
// manipulate the data
  return <UserList 
          userList={userList}
          isLoading={isLoading}  
          hasError={hasError} />
}

Note: one file should only contain one component.

We will do this for each component in the application, the folder structure will look like the following:

src
  userList
     UserListContainer.ts
     UserList.ts
     UserList.stories.ts
     UserList.test.ts
     index.ts // this is responsible for exporting the component

Now, to use UserList component, we will import the UserListContainer to where we need it. When the UserListContainer mounts on load, it will make a query call for the user list data, manipulate the data, and pass it to the UserList component.

With this separation of concern, we can all write scalable and maintainable React code; code that is not only for ourselves but for every other developer who will be working on the project.