Coding Convention: Why your team should adopt one quickly
Your team needs to adopt its coding convention and do it quickly. This is a case of either do it or suffer the consequences.
I am sure you have seen various arguments on issues like tab and space, snake_case and camelCase (DB related), naming convention, etc all these and many more are issues you will eventually have to address whether early on by adopting a team coding convention that will serve as a guide and ensure that everyone can sleep well at night or later on in the development stage where you have to do some tear-down and re-building because you have failed to address an important issue early on.
What is coding convention?
These are sets of guidelines adopted by a software development team which enables the team to write consistent and easy to understand code by all team members. Usually, a team’s coding convention is a set of guidelines which is a document that guides not just how variables and methods should be named or the number of spaces that make a tab but which can also include the overall structure of the code and choice of design pattern used.
Notice that I called it adopted because, in many cases, you will not have to define all these guidelines from scratch but rather use one or a mix of the existing conventions in your team.
A note on best practice
The fact that various best practices at best are silent on some salient issues, then your team needs to develop exactly what is best for it.
Nothing is best about best practices if it does not benefit your team
Why your team should adopt one fast
Adopted team coding convention ensures that the team writes consistent code which means that there will be less back and forth among team members about code clarity.
It helps new team members onboard quickly because they can always have some sort of guide while looking at your codebase in a bid to understand it to be able to add valuable contributions thereby reducing the Turn around Time for delivery and increasing throughput.
It helps in code maintenance. Having uniformity in codebase helps because everyone understands exactly where to find various pieces of code across the codebase and this helps greatly in maintenance.
Faster debugging. When you know where to find what, part of the problems is solved while debugging since you won’t have to start troubleshooting to know the exact location of various files/code in the codebase because there’s a certain way that your code is structured which is clear to all team members.
In general, adopting a team coding convention/guideline early on in the development process helps the team to work more efficiently than when each team members have their different styles which can lead to a problem when trying to integrate various parts of the codebase.
The chaos to expect if you fail to do so.
At best, you are the only developer in your team and you hope to leave as soon as the team starts to expand, by that, new developer team members won’t have your head 😂
Not having or adopting a particular coding convention for your team will lead to delay in development time because part of the time will be spent on arguing what is actually best from individual perspectives while in reality most of these things are really just based on preferences.
Debugging nightmare
Because you are not exactly sure how the other team member has structured his or her code, so much time can be wasted trying to find where various files are in order to be able to use them in debugging.
Useful Tools
Here are some nice open-source tools that can help in enforcing team coding convention. Although it may seem a little not convenient at first, it will be a great time saver in the long run.
Linters: ESLint (JavaScript)
You can find various linters for your equivalent programming languages, they practically do the same thing. If you would like to know how linter works check here
Style guides: (Airbnb - JavaScript, PEP 8 - Python, Google Java style guide - Java)
These are predefined guides that you can adopt for your team and integrate with your linter to the hard work of ensuring every line of code adheres to your adopted team’s coding convention.
In conclusion, whether you choose to address the issue of coding convention early on in the development stage or you leave it to chance and at the mercy of individual team members, one thing is sure, you will still have to address it at some point in your development journey and one will be costly while doing it at the early stage will be beneficial to all.
Can I offer the opposite perspective, having worked on teams with a formal code style policy, and on teams without. On those teams with strong code styles, most of the time in code review was spent checking that the code complied with the code style, to the detriment of whether the code had other major issues. Conversely, with the other teams, code reviews tended to be a bit more productive in terms of reducing the accumulation of technical debt.
Sure, the code ended up being a mish-mash of different styles. But, provided each file was formatted consistently, that was kind of a charm. You could tell instantly who was the main person responsible for that particular file, for instance, by the style it was written in. It’s no more difficult than dealing with individual accents when working with a team of Aussies, Americans, Brits or Scots.
My current team has adopted the Google style guide. IMHO, it is about 1/3 sensible (uncontroversial best practice stuff most people understand), 1/3 unimportant stylistic things, like where to use camel case or snake case, and 1/3 idiotic. We have dropped a number of the idiotic rules, but there is still a lot bandwidth in code review time spent dealing with the idiosyncratic naming conventions of the GSG, and sadly technical debt sailing through, because people are tired.
IMHO, adopt a coding standard that can be enforced by a linter - then everything else should just be free for use. Free up mental bandwidth for the stuff that counts!
Thank you Russell for pointing this out.
I completely agree with you that styles should be enforced by linters (That’s their job 😀) instead of spending valuable time on reviewing such. That way, it is certain that code that does not conform to the team adopted style won’t make it through checks while also giving the team a sense of uniformity across codebase.