Most medium and large software projects have a style guide to ensure different developers write code in a consistent way.
Styles guides document coding conventions on topics like file names, variable names and code indentation.
This article explains why they are beneficial and gives tips on how to adopt them.
Advantages of using a style guide
Style guides provide three benefits that make development more efficient:
- Code that's easier to read
- Clear guidelines when writing code
- Predictable file and variable names
Consistent style choices greatly benefit readability. For example, they mean that indentation reliably communicates the structure of your code.
Variable naming conventions allow you to immediately see that
LoginDialog is a class,
loginDialog is a class instance and
LOGIN_DIALOG is a constant.
When writing code, style guides reduce the number of choices a developer has to make. This allows them to focus on the program's logic instead of making style decisions.
Finally, the most important benefit is that style guides make your modules more predictable. Consistently following the same naming conventions means that you don't need to look up how a property or function name is written. If your style guide says to always use camelCase for function names then you know your function is called
How to adopt a style guide
It's a good idea to use one of these style guides as a starting point. Using an existing style guide helps avoid internal discussions based on personal preferences about the what's best.
Generally, what styling conventions you choose doesn't matter very much, as long as they are followed consistently. If you find that a specific rule isn't working for your team you can always change that rule.
Implicit style guides
Some projects use the concept of an implicit style guide. The idea is that you write your code in such a way that it follows the styling of the code that already exists around it.
I don't like that approach, as every time inconsistent styling slips into the code base it creates a precedent for more inconsistent styling. It can also be difficult to find a precedent in the existing code to make a styling decision on.
Following an implicit style guide is better than not aiming for consistency at all. But, when you have a choice, use a written style guide that reduces ambiguity.
Enforcing style guides
Automated checks mean that style decisions don't take up time during code review. Constant negative feedback by a computer also won't hurt people's feelings as much as repeatedly receiving the same feedback from a co-worker.
Ideally you want to catch code that breaks styling rules as early as possible. Many code editors have tools that validate your code as soon as you write it (e.g. SublimeLinter).
In addition to that, your build server can also run an automated check whenever new code is pushed.
Unfortunately, automated tools aren't built to cover every aspect of a style guide. When they can't detect an issue another developer can point it out in the code review process.
Style guides ensure consistency and predictability across your project.
Ultimately, their goal is to help teams build software more efficiently, so keep in mind this note from Mozilla's style guide:
Of course every rule has an exception, but it's important to know the rules nonetheless!