Deciding how to do things and sticking to it, until a solid reason arises to change it, is important.
In fact a concrete definition of how to do things is even more important than what you actually decide to do. You might lean back now, with a suspicious look on your face, when I say that, but hear me out.
Does it really matter, if private object fields are camelCased instead of PascalCasing them like the public ones or if you _underscorePrefix them additionally? I say “no”! But, what is important is to be consistent.
If you 90% of the time prefix your privates with underscores, 7% of the time just skip the underscore and 3% of the time have public refactored to privates without lower casing the first letter you are in trouble. You cannot know from the name, what you are dealing with.
Also it does not do harm, if you have no special casing for your constants and name them like variables. But if you make a point of FULLY_CAPITALIZING_CONSTANTS, like php likes to do, and just occasionally don’t, someone might trip over it.
Things to put into coding guidelines
Most of the aspects of programming that you can form an opinion on could be covered by a coding guideline, just like style guides cover choices about font selection, margins and colours.
Some popular examples are:
- Indentation
- 2 spaces, 4 spaces or 1 tab?
- Ordering of class members
- public -> protected -> private
- fields -> constructors -> properties -> methods
- static -> instance
- Capitalisation of member names
- All classes, properties & methods in PascalCase
- All local variables and parameters in camelCase
- Whitespaces & line breaks
- Opening and closing curly brackets of multiline-blocks lay on a separate line or just the closing ones
- Closing curly brackets of multiline blocks are followed by an empty line or not
- Parameter lists have a space character after the comma or not
- Narrowing down alternatives
- Single quoted strings vs. double quoted strings in languages that don’t make a difference (JavaScript, I’m talking to you!)
- Architecture
- Layers, onion, micro services
- Patterns to use
- Builder, adapter, façade
- Code quality metrics
- Unit test coverage
- Integration tests
- Cyclomatic or cognitive complexity
- Method and class sizes
- Commenting etiquette
Who benefits from coding guidelines?
The whole team; all the developers on the project and even the management. If you have thorough coding guidelines and adhere to them your code will be easier to understand and read. It is harder to read a file with mixed indentations, line break points and naming schemes than a clearly structured one. Also it is easier to understand a piece of code if you already know what patterns and architectural choices will be most likely applicable.
This slims onboarding time as well as the time to get productive on a new ticket. In return this means lower overall time consumption per ticket, which makes the management happy.
Concrete benefits from having them
To create real world benefits from guidelines it takes some dedication and discipline. They need to get used throughout the whole project to be really helpful.
As mentioned above coding guidelines make the code more readable and lower onboarding time. As soon as testing etiquette and patterns get involved, it also reduces the chance of bugs slipping into production.
Another thing that a good coding guideline helps with is to lower ambiguity. The guideline makes it more likely that you know what you’re dealing with by glancing over the code.
A good way to put it is this: the bigger your code base is or is expected to become, the more can a thorough coding guideline improve the code quality in the long run.
How to enforce them
Just putting the guidelines in a root README.md and telling every new developer on the project to read them has proven to be of little success. If you rely on this you will most likely clean up after them and the file is no more use than a location to point to if you want to accuse someone of being messy. (Don’t do that!)
There are automatic tools that can help you with some points like formatting the code. Most of them hook into the git-hook-system to make commits or pushes (to certain branches) fail if some criteria are not met.
These can be very valuable, but they have one downside: They cannot be put into .git/hooks at clone time. There needs to be some post-clone action. How this would work totally depends on the language you write in and the tools you use. I have seen solutions based on npm install side-effects, composer and others. Or you could go for manual onboarding; putting a cmd/sh/PoSH-Script into your project that installs the hooks for you and tell every new dev to execute it.
For complexity there are services that pre-check github pull requests. They can flag them accordingly and point out too complex structures.
But when arriving at architecture and patterns you are out of luck, as far as I know. Here manual onboarding seems without alternative. It is still a good idea to have the README.md or CONTRIBUTING.md with the details and possibly a link list to the used patterns.
Boilerplates
Often writing your own coding guideline from scratch is a daunting task with low immediately visible return of investment. It might even be too big a task to be worth it.
But often you don’t have to do so. Most languages and frameworks have their own guidelines publicly available and ready to use. The .NET coding conventions are on microsofts docs-page.
You could sit together with your team, look up relevant existing standards and do your own mix and match and then tug on your very own preferences. Et voilà a full-blown coding guideline for a sliver of the cost.
Tooling
A tool I use to enforce guidelines is StyleCop. It is a free Visual Studio plug-in that runs static analysis on your formatting and commenting. It still needs to be run manually, but it is a great tool to bring everyone in the team on the same page. Rules and exceptions can be put into a Settings.StyleCop file that can be checked into the versioning system (e.g. Git).
Most important things like complete method and property header comments, no superfluous line breaks, proper indentation and proper formatting can be checked with this tool.
I use StyleCop on most examples that I commit on GitHub for this blog.