How to standardize codebases across teams

5 minutes

Crafting a style guide involves finding the right mix of detailed guidelines and open-ended suggestions.

As your software team grows with new features, hires, and teams, maintaining standards and consistency in the codebase becomes increasingly difficult. It’s one thing setting a technical standard, but enforcing it (or knowing when not to enforce it) is a much harder challenge. However, just like with many hurdles, there are practical steps you can take to overcome them. 

Creating a style guide

Before we can talk about enforcing a standard, you have to have a standard to enforce. Think carefully about what you’d like to keep consistent across your codebase: recognize that not every developer on the team should write code that perfectly matches your own technique. Embrace each developer’s stylistic preferences. 

When crafting your style guide, center the things you really care about and go from there. Depending on the language(s) you work with, there might be certain features you want everyone to avoid. For example, in JavaScript you will want to avoid the use of the `var` keyword in favor of `const` and `let`. This might seem obvious to you, but remember that your style guide is going to be used by developers with a mixed background of experience. If a developer who joins your team hasn’t worked with JavaScript before, this advice in the style guide will be invaluable. On the other hand, try to avoid getting into the weeds of formatting. Your style guide can say, “We use tool X for code formatting” rather than list every single formatting preference you have, as there’s no need to explain each one. 

Areas where teams and companies often differ are good candidates for clarification in the style guide. Automated testing is a great example; what is your desired ratio of unit tests, integration tests, and/or end-to-end tests? Some teams I’ve worked on require every feature to have a distinct end-to-end test, whilst others prefer lower-level unit tests as much as possible. There is no global right answer to this, and it depends on the type of software you are building and how you want to build it, so encode it into your style guide. Picture a developer working on their first change for your team; what are all the things you want them to know about their approach?

Leaving room for your team to diverge

Try to avoid creating a style guide that is too prescriptive or one that doesn’t give your team members room to flex. There is rarely a rule that applies to all code and developers might likely find good reasons to deviate slightly from the style guide. So, ensure your guide aligns with your preferences, but allows room for developer flexibility in certain contexts if they think it will produce clearer code. Your style guide needs to leave room for your team to feel trusted and comfortable, not like they’re coding with a hand tied behind their back.

Setting expectations on approval and code review

In a previous role, I worked on a team where every single change had to be reviewed by the team lead. Considering there were seven of us and only one team lead, their thorough and meticulous review process had two major consequences:

1. The team was completely bottlenecked; it could be days before your change was reviewed, with no way to speed it up. Small fixes took a disproportionate amount of time to land in the codebase. If your change had to go live by a certain date you had to ensure the review was ready days before. This was incredibly frustrating for everyone and killed any momentum the team had.
2. No one on the team felt trusted. Even developers who had been there multiple years couldn’t review code. No one was invested in the codebase, team, or process, because they didn’t feel like they had any ownership or were empowered to make decisions.

Creating this sort of culture and process is very unhealthy and suboptimal. At the same time, it is important to have the team aligned on how they approach code review and sign off on proposed features or architectural decisions. 

As a tech lead of a team of six engineers, I like to ask that every design document comes through me for approval, because that lets me stay on top of the architecture and high-level design decisions. I can spot potential conflicts across features and suggest alternatives. When it comes to code review, though, I simply ask people to use their judgment – involve me if they think I can be useful or would want to be involved. Otherwise,  pick another appropriate team member. This is something we have in our style guide too – not everything in there should be focused on how your code is written.

Lean on automation

A team incorporates a code review step for two primary reasons:

1. To share knowledge across the team and between developers.
2. To identify pitfalls in an implementation’s design and suggest alternatives.

Notice what isn’t there? Identifying style guide divergence or formatting changes. The problem of standardizing code formatting across a team has long been solved by code formatters – tools that can take your code and reformat it to a consistent style. These exist in nearly all mainstream languages now and some languages even have multiple to choose from.

Your style guide should align with your code formatting tool(s) of choice and require all developers to use them when working on their code. Automatic code formatting is also a productivity boost for developers – it removes any need to debate menial details such as “tabs vs spaces” or if to use semicolons in JavaScript. Don’t let your team get bogged down in stylistic arguments; pick a tool and use it.

In addition to formatting, custom scripts can also improve your team’s productivity and adherence to the style guide. Consider creating a script that automatically generates boilerplate code for your front-end components, or implements bespoke checks around naming conventions. In our team, we have many of these checks that run as the developer is editing (ours are implemented as custom ESLint rules). We then also have checks implemented as Git pre-commit hooks to check for outdated test files, up-to-date localization strings, and more.

Striking the balance

Creating a style guide that your team wants to adhere to is a case of striking a balance between prescription, guidance, and tooling. By thoughtfully combining all three, you can create a technical standard across your team that will aid consistency, making the codebase more approachable and keeping your team productive.