Why a coding standard document is necessary for every team.
Every time I join a new organization, the very first thing I ask my seniors is if they have any coding standard documentation that the team follows?
To my surprise, I’ve never got an answer like
We have a coding document that describes the patterns we use, test case strategies, deployment strategies, naming conventions, and here’s the link. Happy reading.
It seems like everyone codes based on just get it done and it ship it we’ll clean up the code later once we are done mentality.
The real fun begins when someone tries to introduce some coding discipline and faces a solid pushback from the team, not because they don’t like coding standards but because they assume that having to code in a certain way will slow them down in completing their task.
A team consists of various developers coming from different companies and bringing the practices they followed from their previous companies into the project.
What happens when there’s no coding standard document?
You’ll see different coding styles across the codebase, developers will use their experience of how they solved the issue in their previous organization and lay it down in the codebase. Some approach maybe good and some will be hacks.
If such project goes for an audit then it looks not only bad on the team but also bad on the company.
In my opinion not having a coding standard document is bad. It’s the major reason why a majority of the code base I have worked with have
❌ Poor naming conventions of functions and variables.
❌ Tight coupling.
❌ Abuse of certain design patterns.
❌ Lot of hack-based solutions.
❌ No test cases.
Sure the code works, and does what it’s supposed to but introducing change to such codebase is like jumping in the lake of hungry alligators.
It’s so confusing to read and filled with so many different styles and hacks that one takes a lot of time to figure out what’s going on in the project.
So who’s responsibility is it to produce a standard document? Is the company or is it the developers?
In my opinion it’s the development team.
If the company doesn’t have such document, the senior developer and the tech lead must come up with a detailed document of what practices they need to follow.
It’s the responsibility of the senior developer and the tech lead to make sure that the project follows all the coding practices mentioned in the document and ask the developers to make changes accordingly in code reviews.
If you don’t have that much time and are on a slim deadline for projects all the time, then I suggest at least installing linter in your source code.
For Swift, I use a linter called as SwiftLint which has helped me a lot in enforcing good coding practices of the swift programming language, this way I am not doing something goofy with the code.
SwiftLint won’t tell you that a variable name should be productDescription and not abcZ OR don’t use Factory pattern use a builder pattern that’s something the team has to figure out keeping maintainability in mind.
If you don’t want to invest time in writing this document then please search online for any good practice document for your programming language, this way you are not spending time writing each and every rule on your own.
Just refer to the link and make the necessary changes and share that link with the entire team.
The only thing I would make sure is the version of the programming language for which those standards were written, it has to be latest or one version old but not too old because then the document you are refereeing to is obsolete.
There’s no point in refereeing to a coding standard document written for Swift 1.0 when the project uses Swift 5.6 or above.
I hope this read was helpful, let me know in the comments what you think about having such document.