How to create effective coding standards for your project

Have you ever been in a situation where you join a new team and start reading the codebase to understand the project you will be working on? And then… you get confused by the way other team members write their code. Sometimes, snake_case is used for file names and other times it’s camelCase. Sometimes, people put all properties of an component on the same line, while others spread them across multiple lines. The way variables are named can also slow you down, especially when the names aren’t descriptive enough to reveal their purpose.

The code may still run without any issues but for us—developers— we spend more time reading code than writing it. This can become a real problem. That is why a coding convention is essential for any team. I believe a good coding convention isn’t only about code formatting (which makes the code easier to read), but also about how we write code in a way that makes it easier to understand.

Let’s create a coding convention that can help our team enhance both the code readability and quality. From my experience, a good convention should include the following sections:

Introduction

Just like any other type of documentation, a coding convention should start with an introduction that explains why the document exists. It could be similar to the first paragraph of this article, but it should be written in a more formal tone. Specifically, it should outlines the benefits of following coding convention within a team and highlights any important notes that all team members should keep in mind when working with the codebase.

Project specific rules

In this section, we include all the specific rules that should be highly prioritized when working on the project. These rules may be influenced by business requirements, technical constraints, or project context.

For example, in a SaaS project, if you’re working on the frontend and plan to use a third-party npm package, you should ensure that its license allows commercial use. In another case, if the project’s domain involves payments or sensitive finance transactions , it may be necessary to avoid introducing third-party libraries for security and compliance reasons.

General principles

To encourage clean code habits across the team, it’s helpful to mention a few common software design principles and encourage everyone to follow them. Applying these principles can significantly improve the maintainability and re-usability of the codebase—especially for newer or less experienced team members. Some core principles you can introduce are:

Single responsibility – Each function or component should have one clear purpose or responsibility.
Don’t repeat yourself (DRY) – Avoid duplicating code. Instead, extract common logic into reusable functions or components.
Keep it simple and short (KISS) – Write code that is easy to understand and not overly complicated.
You aren’t gonna need it (YAGNI) – Don’t implement functionality until it is actually needed.

These principles act as a foundation for writing consistent, scalable and clean code.

Code formatting

Code formatting is often the first thing that comes to mind when we talk about coding conventions. Obviously, to enhance the code readability, the code format should be consistent across the entire project.

We can define a set of specific formatting rules, such as:

Whether to use 2 or 4 spaces for indentation
Using double quotes or single quote for string values
Whether to include semicolons at the end of statements (especially in language like JavaScript, for where semicolons are optional)
Whether to use brackets for single-line conditionals or loops
And many more…

Fortunately, these formatting rules can be easily enforced and automatically fixed using tools like ESLint and Prettier.

Git

Git, or version control in general, is an essential tool for software development. Working with git involves more than running git add, git commit and git push. It also includes reading commit histories during code reviews and tracking changes when debugging issues. A well-defined commit message can make these task much easier and more efficient.

To support this process, it’s helpful to follow a consistent convention for commit messages and branching names:

Branches: <{feat|fix|chore|docs|refactor}>/<ticket number>-<optional short description>

Example: feat/A-001-live-search
Commits: <{feat|fix|chore|docs|refactor}>(ticket number):<description>

Example: fix(A-002): fixed live search logic

Using a structured format makes it easier to understand the purpose of changes at a glance and improve the collaboration across the team.

To learn more about this convention and its benefits, you can explore Conventional Commits.

Variable naming

Variable naming conventions often depend on the programming language being used. For example, in JavaScript, camelCase is commonly prefered, while in Ruby, snake_case is more typical. Regardless of the chosen style, the most important point is consistency. It’s essential to enforce a single naming convention across the team to maintain a consistent and readable codebase.

The more descriptive a variable name is, the faster we can understand the code logic. The name “data“ could be the most popular word that we encounter in software development, but do you believe this is the word that we should avoid using the most in our code base? This name is too general to convey any meaningful information about the value it holds. We should use descriptive names that clearly reflect their role in the system. For instance:

// ❌ should not
    if (!dataExists()) {
        return '<div>Loading Data...</div>';
    }
// ✅ should
    if (!peopleFound()) {
        return '<div>Loading People...</div>';
    }

When working with front end projects, I follow a set of naming conventions to make the code more readable and maintainable:

For boolean variables

When naming boolean variables, it’s important to use a clear name to represent the true/false condition. Using meaningful prefixes like is, has, can, should, enable, and allow can make the variable’s purpose is immediately obvious.

Some examples:

isLoading
hasError
shouldShow
canEdit
allowAccess

Additionally, it’s a good practice to avoid using negative words in boolean names, as they can lead to confusion when used in conditional logic:

❌ isNotEnabled
✅ isDisabled

❌ isNotValid
✅ isInvalid

For functions

A function name should start with a verb because functions perform actions. Examples:

const getUserProfile = () => {...}
const removeUserContact = () => {...}

Similar to boolean variables, using prefix for function names can help us quickly understand the function’s purpose and where they are likely to be used. Let’s take look at common prefixed I use:

handle: Used for functions that can be called directly by the user interactions in the UI. Example:
```
  const handleClick = () => {...}
  const hanldeSubmit = () => {...}
```

format : Used for functions that process data to display in the UI. Example:

  const formatCurrency = () => {...}
  const formatTime = () => {...}

transform : Used for functions that convert or prepare data before sending it to an API. Example:
```
  const transformFormData = () => {...}
```
on: Used for defining callback props in components, especially in React. Example
```
  <UserForm onSubmit={handleSubmit} onCancel={handleCancel} />
```
parse: Used for functions that convert one structure to another structure. Typically, the returned value from these functions should be used as an immediate value and then consumed by another function:
```
  const parseUserData = () => {...};

  const onFetchSuccess = (response) => {
    const user = parseUserData(response);
    updateUserStore(user);
  };
```

Framework specific guidelines

Each framework or library come with its own coding style and best practices. Enforcing a consistent style and adhering to these best practices help improve both the code base consistency and the product quality. That’s why it’s important to include a dedicated section for framework-specific guidelines in the coding convention.

Start by examining the framework your team is working with and identifying the common styles and best practices used by its community. Then, adapt and apply those rules to your project.

For example, with Vue.js, we might set the rules such as:

Ensure the order of <template>, <script> and <style> tags in Single-File Components consistent across the project.
Always use directive shorthands (: for v-bind, @ for on and # for v-slot).
Always use a unique key attribute with v-for directives to help Vue efficiently track elements.
Avoid using v-if and v-for on the same element to prevent rendering issues and improve readability

Conclusion

It’s important to establish standards for our codebase, and coding conventions are one of the most effective ways to achieve this. To create and apply coding convention effectively, we need to focus on the following:

Define essential and necessary rules and convention along with a method to evaluate the implementation.
Ensure all team members are aware of the existence of this documentation. They should understand the benefits of following these standards so they can consistently apply them in their daily work.

If the convention document is properly defined and strictly followed, we will enhance the readability, maintainability of the code base as well as the quality of our products. In addition, we can foster better collaboration and understanding among team members.