Every developer has their own preferences and should always provide their input—every opinion has the same weight. But, if the developer works in a team, then the team rules.
A team should discuss and agree on a single formatting style, and every member of that team should comply and apply that same code style. Furthermore, every team member should strive and be on the look out to guarantee the code style is being followed. The code style should be clear and documented in an easily accessible place. The style guide is, however, a living document; it should not be written in stone. Just like us, code and teams change. Naturally, a code style will change from time to time—every member is free to propose changes, and every team member is free to discuss their own settlements and review their own past decisions. If possible, you should document the reasons for changes in style if they are substantial or polemic—like deciding to change, in the middle of a project, from using spaces instead of tabs for indentation.
In this blog post, we’ll describe what a code style guide should contain, how to maintain one, and when and how to use it. Let’s start with some key questions you should ask when drafting your own code style guide:
- What is the maximum line length?
- Are we using tabs or spaces for indentation?
- Are we ending files with a new line?
- Are we adding empty lines between function declarations?
- Are we allowing indentation breaks? In which cases?
- Should all function arguments be inline? When should we break arguments in a new line?
- Should we use dangling commas at the end of each property in an object?
- What is the maximum line length we are allowing?
- Is there a maximum size for files?
- Spaces between function name and parenthesis?
- Inline or brackets on a new line (for functions, modules, ifs)?
- Are ternary operators allowed? When? How much nesting?
- When and if we should use spaces with operators?
- Should arrow functions always have parenthesis around single arguments?
- Should arrow functions always have brackets and return statements?
- Do single statement ifs need to have brackets?
- Cast to Boolean: Boolean(variableName) or !!variableName ?
- Cast to string: String(value) or allow operations such as value += ''?
This small list is just a starting point for discussion, and numerous other topics may be included. A good code style guide does not need to be finished in one day—sometimes, no clear preferences exist, and teams need some time to see what will work best for their preferences in general.
What’s important is to document code styling decisions and to make this documentation accessible to all members of the team—if developers outside the team will contribute code, then they should be aware and have access to the code style guidelines too. If possible, prefer storing the guidelines where it can be accessible without needing to download a file, keeping a single source of truth of the updated file.
Generally speaking, this documentation consists of the rules that have been decided upon by the team and examples of dos and don’ts. As time passes, edge cases will appear, which should be brought into the discussion and should be documented. These discussions can be as simple as a message in a group chat or a meeting if it’s a topic that deserves more thought.
A good practice is to document changes with dates (dating when was the document changed and capturing its previous state) and who was involved in the discussion, if not the whole team. You should, however, keep decisions on hold until all members of the team can have time to think and express their opinions. After all, code style guidelines should serve the team, not be the cause of problems or a reason for team members to fight.
After the code style guidelines are mature enough to use, you must enforce and maintain them. Not everyone is free from mistakes, and sometimes, a developer may violate a rule in the code style guidelines—whether from misinterpretation or being too focused on one task, mishaps can happen. All team members should have a mindset focused on improvement—take a code review as a compliment and an opportunity to improve, instead of as a personal critique.
Code review is a major opportunity for checking on and educating fellow team members. However, you can also automate this kind of verifications, which is strongly advised. Taking responsibility of checking, reviewing, and enforcing code styling is good for everyone, saves time, and avoids mistakes. Even when automated, adherence should be still checked in code review.
Editor’s note: This post has been adapted from a section of the book Clean SAPUI5: A Style Guide for Developers by Daniel Bertolozi, Arnaud Buchholz, Klaus Haeuptle, Rodrigo Jordão, Christian Lehmann, and Narendran Natarajan Vaithianathan.
Comments