09-11-2014 by Sebastian Schürmann
Coding conventions sound so easy, but get hard over the course of a longer project and with bigger team size. With a little feedback and forth with Johann Peter Hartmann, the following principles for a coding standard were up for discussion.
My list of tipps should help you find a standard and keep it up.
1. They apply for everyone in the team.
No developer, in no situation should be exempt of the conventions. It might sound dogmatic, but this is a rule that applies for everyone. Even for $pointyhairyboss, if he is still pushing to the codebase.
2. There is no perfect convention for every given project.
I see this discussion revolve again and again: Developers looking for “the standard”. Where do I set my braces, which kind of whitespace do I use? Please tell me. I am to smart to look for THE standard, give me any standard and I will adhere to it.
3. Automate checking
No one wants to check, what could be millions line of code, by hand ot just looking at the code. Tools can help you with that. What ever you decide, try to create an automated check for violations and make this one available to all the developers working on the software.
4. Have examples and explanations
Coding conventions may seem to be a very subjective thing. But when explained properly, in a markdown, text file or wiki page it gets easier to accept to code by standards that are not your own (yet).
5. Your codebase must have 0 violations at all time
With command line tools and checking before you push stuff to a repository, this should be easy. There might me exceptions, but make sure you group them into modules exempt from the checking process or make other wise sure the initial thought of a same structured codebase does not get undermined. See 6.
6. Change if required
If the rules don’t fit, change them to better ones. Migrate the module to the new rules. Do not only change the rules. Change the code as well.
7. Everyone is responsible not only for his own conventions
Where ever you are in a pice of code, you are encouraged to fix any violations or add a example here and there. Didn’t you find enough comments? Cool, add some. Something is formatted wonky? Fix it! Somebody used spaces? Change it to tabs if the spec says so. Where ever you are in the code, a OneButtonTest will be a good practice to look at.
8. Make conventions per module, not per team
Different modules might be written in different times and adhere to different standards. So splitting up parts of your software that follows a very different style might be reasonable. In Javascript and a browser environment you would use tools like component and bower to get things back together. Small modules help you maintain different styles. Think about it: If you have a long running project, it’s very likely you will have more than one standard. And small modules allow for different ones in different occasions and situations. One argumentative nail in the coffin of Big ball of mud designs
This was my list of hints. What are yours?
8. Use existing conventions and starndards
Tobias Schlitt argued, that the use of already existing standards has a lot of advantages over creating your own ones. In PHP there is the PSR- Series of standards. These are pretty good and you will find ready made tools and documentation out there.