Synced Style
Developers struggle to maintain code consistency, negatively affecting code maintainability and reliability.
We wish to maintain a higher level of code discipline, increasing the reliability of the code.
Define a consistent coding style for your team, document it, use it, and enforce it.
If possible, add automation to your build process to point out any irregularities.
Even if code is not fully up to spec, it is better to be consistent with the rest of the surrounding code than to introduce yet another style to
an existing project. If you are going to change conventions midway through the life-cycle of a codebase, be sure to change all of it.
Do not let inconsistent styles creep into your repositories.
Being consistent within a codebase does not mean your need to apply the same style to all repositories within your project. It can be a viable option to apply a certain style within one repository, and a different one in another. As long as the code is consistent with it's surrounding, you will get the benefit of pattern recognition.
Well-suited for teams working on projects where code maintainability and readability are paramount, such as large-scale enterprise applications or long-term software projects. It is particularly beneficial in environments where multiple developers collaborate on the same codebase, ensuring consistency and reducing cognitive load. This pattern is also effective in organizations that prioritize code quality and have the resources to invest in defining, documenting, and enforcing coding standards.
The following factors support effective application of the practice:
The following factors prevent effective application of the practice:
A great example of this is the use of brackets to identify code blocks in Java. While not strictly necessary to make your code compile or work, many teams explicitly ask their developers to include brackets, even on conditionals that could be written as one-liners. This particular convention tends to irk newer developers who like their code to be as concise as possible. While brevity is a usually good, at times it can confuse your readers.
Let’s have a quick look at the code below, which checks whether we are under attack, and whether to launch a retaliatory nuclear strike.
public void failSafe(boolean thePresidentIsDead){
if(thePresidentIsDead)
launchNukes();
businessAsUsual();
}
Now imagine someone in the team is tasked to add logging statements to the entire codebase. They do as they are told, resulting in the code below. At first glance, everything looks fine. Can you spot the cataclysmic mistake?
public void failSafe(boolean thePresidentIsDead){
LOG.info("Checking to see if everything is still okay...");
if(thePresidentIsDead)
LOG.warn("OMG! You killed him. You bastards!");
launchNukes();
LOG.info("Carry on, carrying on");
businessAsUsual();
}
The nukes will be launched, regardless of the president being alive or not. A simple log statement, combined with misleading indentation has set forth a thermonuclear apocalypse.
Most (semi-mature) languages have a preferred style. It is usually wise to stick to it, even if you do not personally like it. As a few examples: Java is written mostly in camelCase, C# uses PascalCase for everything but variables, Python and JavaScript developers tend to put expected variable types in the names. The list on small and large differences between different language default writing styles is long.
Even on your project, you might decide to use a particular spacing/indentation convention, method ordering, or you might enforce a certain level of test coverage for parts of your project. Basically: there are a lot of custom conventions that exist within a project. On most projects, the biggest part of review comments are related to people not following the preferred style correctly.
In order to avoid mostly useless back-and-forth on stylistic differences, delegate these things to an automated system. There are plenty of good linters and static code analysis tools out there that let your automatically find and highlight issues with the style of code that is being written. Additionally: most modern IDE’s allow developers to import a stylesheet into their tooling, and reformat the code prior to committing it to the source control system.
tip: Let a machine handle the easily spotted and corrected “issues” in your code base, enforcing consistency. Spend your time on digging into the important things, such as functionality or the architecture of the code.