Setting up a set of rules for the whole company to adhere to can be tricky. Not everyone is convinced about the benefits and even the biggest fans of such a set of rules have trouble agreeing on what exactly the rules ought to be. Tabs or spaces, for example, have been the subject of many a heated discussion and will probably continue to be so long after our future robotic overlords have taken over.
This is because code conventions are not about one clear Good™ way to write code. If that were the case, the discussion would have been closed ages ago. And in a way it was, at least for Java, by Oracle, but their conventions have not been updated since 1999(!). Almost two decades later, it seems like every project or company employs its own unique set of rules.
The real reason for not letting every developer decide independently is that it can decrease the readability and clarity of your code. If you know up front how the code will be structured, it will be easier to understand it. You don’t have to waste time figuring out if, for example, that empty
else statement was a stylistic choice or if your colleague forgot to fill it in.
Note that, though this blog is mostly from a Java perspective, the process is applicable to any other language.
Document your code conventions
Most workplaces already have an unwritten set of conventions, passed down orally from the seasoned veterans to the new arrivals. This is the easiest place to start with, as these oral rules will be met with the least bit of resistance. After all, everyone involved has already been applying them anyway.
Moreover, documenting these rules comes in handy specifically for newcomers, because they can easily check their own code against the company’s conventions before they submit it for a review.
Once the unwritten rules have been documented in a place where everyone knows how to find them, it is time for an “input round”. This is a period during which everyone involved can suggest new rules or adaptations. End the input round by setting up a meeting to explain the rules and to go over the suggestions. In that meeting, all suggestions are debated, until you have a set of rules that everyone can agree upon. These are your “official” code conventions from that point onwards.
Automate your code conventions
Even rules that everyone agreed upon can be forgotten from time to time. Hopefully, those slip-ups will be picked up in a code review, but it is of course even better if they never reach that point. This is where automatisation can be of great help, but only if the configuration of your preferred tool matches your rulebook. If the rulebook doesn’t match, it will only amount to bigger confusion about what the correct set of rules are.
The most important tool for enforcing code conventions is probably the IDE. For our IDE, we choose IntelliJ, but you will probably have similar options in your preferred IDE. Another great tool is SonarQube, which can be seen as the next step because it will analyse your entire codebase.
IntelliJ can help you in two ways: The layout-related rules can be configured under
File > Settings > Editor > Code Style, the other rules under
Inspections. IntelliJ already comes with default settings, but you should always adapt them to match your own conventions.
You can do this simply by going to
File > Settings > Editor > Inspections where you will find IntelliJ’s default inspection profile. Then click on the gear icon and choose
Duplicate…; this will give you a copy of the default profile, which you can give a new name and adapt to your needs. It might take some time to check each rule of the profile against the one you decided on before, but luckily you only have to do this once.
Tip: Again on the gear icon, choose
Copy to IDE… to have a locally stored version that you can easily import into all future projects with
Copy to project…. Configuring the Code Style settings works in a similar manner. These settings are then stored in XML files that you can check in into your favourite VCS, so that everyone in your project will have them.
Now, when you do something that is against your coding conventions, IntelliJ will highlight it in orange, or underline it in red or green, depending on the kind of rule you violated. For most of these issues, IntelliJ will have a quick fix ready to correct the issue. You can also opt for a full code review:
Right click > Analyze > Inspect Code… will show you a pop-up with a couple of options of which to choose from. Though the default is to check your current file, you can always change the scope to open files, changed files,… and so on. It isn’t such a big deal if you forgot a couple of rules: Once you start using the inspection profile while coding, you will notice the warnings and you can adapt the profile right there and then. Just check it in again and everyone will have the corrected version.
By checking the boxes when you are committing, like in the figure above, IntelliJ will automatically apply your code style settings (e.g. adding extra spaces), and warn you if you left any TODOs or issues in the files that you are trying to commit. The last checkbox is for the SonarLint plugin, which will link your SonarQube configuration to IntelliJ (see below).
SonarQube’s quality profile
The tool comes especially in handy when you want to keep an eye on how the overall quality of the codebase is evolving (e.g. you can see what the new issues are compared to the previous run, and there is a blame-option).
At Foreach, we use SonarQube to analyse feature branches and we have a rule that no “red” branch can be merged to our main branch. Normally, SonarQube works project-based, but with our Maven plugin you can run it for each branch with Bamboo. It compares the new code with the original branch to make sure that you don’t insert new issues in the code base.
Just like IntelliJ, SonarQube comes with a default set of rules, called a “quality profile”. And just like in IntelliJ, you start by duplicating it. SonarQube has even more rules available than IntelliJ, so it can really take a while if you want to go over them all. It might be easier to just look at the reported issues of the last run. Under the
Rule filter, you will see the rules that are violated most often and you can deactivate the ones that don’t fit in the quality profile.
It can also come in handy to adapt the “quality gates”, to a number that fits your conventions, for example for code coverage. Quality gates are thresholds for the reports in the interface, like how many code smells are allowed before you give the project an orange or red status.
Not set in stone
It is very important to note that code conventions should never be seen as set in stone, otherwise we would still be using the guidelines of Oracle. New colleagues will bring new ideas, new technologies will arise both in your language and in hardware, ... Your code conventions should evolve constantly, adapting to modern times. In short, just make sure to keep the configuration of your tools up to date and everything will be alright.