Code consistency is essential but arguing about coding style is not productive.
Why does code consistency matter?
A consistent code base makes developers’ lives better.
Reading and understanding code that follows a coding standard is a lot easier. Even the parts of code you rarely, if ever, work with are less intimidating.
Code that is easier to read is code that is easier to review. A consistent code style makes code reviews more efficient and thorough because it allows focusing on the important aspects of the change.
Writing code is more effortless because you don’t need to use your mental energy to find the best way to format it. In larger code bases, a consistent style allows applying extensive automated code transformations (a.k.a. codemods) without many misses.
Searching the code is more effective. The consistent structure makes it easier to create search terms that work well. Plus, you can quickly tell if what you found is what you were looking for.
What happens if there are no coding guidelines in place?
Without clear coding guidelines, teams waste time arguing over coding styles. I have yet to see two software developers agree on the style, let alone witness one convince another to adopt their style. What I have seen, however, was diff reviews where obvious bugs or design issues were missed because the diff was dominated by heated (and sometimes personal) arguments about code style.
I once worked in a codebase where a class had four different conventions for naming private variables: underscore prefixed (_name), “m” prefixed (mName), “m_” prefixed (m_Name), no prefix (name). But that was just the tip of the iceberg. The reason for this madness was that four developers, each with their preferred style, who actively worked on this file wouldn’t compromise. Everyone dreaded modifying this file because they knew that the review would take ages and spark conflicting comments (occasionally turning into flamewars) over the chosen coding convention.
How to implement coding guidelines?
If your team doesn’t have coding style guidelines, consider setting them up to unlock the benefits discussed above. However, be warned - it won’t be easy. The main issue is that everyone has their preferred style and, it is tough to create guidelines that satisfy everyone. Since reaching an agreement can be difficult, adopting coding guidelines from other companies or using the default settings from your IDE might be the easiest practical solution. Securing support from your manager and/or a senior engineer on your team before you begin can play a key role in ensuring its success.
Ensuring that style violations are easy to detect and fix is crucial. They should be highlighted both in the IDE and during code reviews, and fixing them should not require more than a few keystrokes. Fortunately, all popular IDEs offer now excellent support for coding guidelines, including project-specific coding guidelines.
The role of tooling cannot be overstated. I witnessed first-hand how inadequate tooling caused an attempt to implement coding guidelines to fail. In my team, we introduced a standalone linter that had to be run from the command line. Reported issues had to be fixed manually. This process was not only tedious but often required several iterations. Because style issues weren’t shown in the code review tool, many of them slipped through, burdening the next person who touched the file. Before long, fewer and fewer team members followed this process and eventually, the initiative was abandoned.
How to deal with code written before coding guidelines were implemented?
Once you have implemented coding guidelines there is one more problem to solve: what do to with the existing code that doesn’t follow the guidelines? Generally, there are two approaches: fixing the code to match new guidelines or leaving it as is. Each option has its pros and cons.
Updating all your code to comply with new coding standards can quickly get you to a clean state. Typically, it involves sending a huge diff that re-formats a significant portion, if not all, of the code. This approach has two major drawbacks. Firstly, it can be highly disruptive for the team. The formatting diff can interfere with ongoing work and may make familiar code hard to recognize. If you decide to go with this approach, choose a time that doesn’t put important deadlines at risk, giving developers time to adjust. Secondly, the big re-formatting will make the change history hard to follow. Finding what changed between commits from before and after “the big diff” will be difficult as it would seem like everything has changed.
You can choose to keep the existing code unchanged and enforce applying new guidelines only to new code. This approach won’t give you an instantly consistent code base, but over time, your code will gradually move towards the ideal state. Frequently modified files will comply with the new guidelines sooner, while others may never get there. This approach is much less disruptive than the previous one.
You can also combine the two approaches. Start by enforcing the new guidelines only on new code to minimize disruption. Then, after some time, update all the remaining code to match the guidelines. The impact of the second phase should be relatively small because it would only involve code that isn’t frequently looked at.
Top comments (0)