Why use a style guide?
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 showDialog, not show_diaog or ShowDialog.
How to adopt a style guide
Most popular open-source projects include style guides, and many companies have published the ones they use. For example, you can have a look at the JavaScript style guides at Google and AirBnB, or the style guide for the jQuery source code.
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
As much as possible you should rely on automated tools to enforce style guides. For example, you can use JSCS to check JavaScript code or CSS Lint for CSS.
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.
Summary
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!