I think there are actually two things to address, and I would in fact consider them separately because they cannot be approached in the same manner, though I find both important.
- The technical aspect: which aims at avoiding risky or ill-formed code (even if accepted by the compiler/interpreter)
- The presentation aspect: which concerns itself with making the program clear to readers
The technical aspect I qualify of Coding Standard, as do Herb Sutter and Andrei Alexandrescu with their C++ Coding Standards. The presentation I qualify of Coding Style, which includes naming convention, indentation, etc...
Because it is purely technical, a Coding Standard can be mostly objective. As such every rule should be supported by a reason. In the book I referred to each item has:
- A title, simple and to the point
- A summary, which explains the title
- A discussion, which illustrate the issue of doing otherwise and thus states the rationale
- optional Some examples, because a good example is worth a thousand words
- optional A list of exceptions for which this rule cannot be applied, sometimes with work arounds
- A list of references (other books, websites) that have discussed this point
Rationale and Exceptions are very important, as they summarize the why and when.
The title shall be explicit enough that during reviews one only need to have a list of titles (cheat sheet) to work with. And obviously, group the items by category to make it easier to look out for one.
Sutter and Alexandrescu managed to have a list of only a hundred items, even though C++ is deemed hairy ;)
This part is generally less objective (and can be downright subjective). The intent here is to guarantee consistency, because this helps maintainers and new comers.
You do not want to enter a holy-war about which indentation or brace style is better here, there are forums for this: so in this category you do things by consensus > majority vote > arbitrary decision by leader(s).
For an example of formatting, see the list of options of Artistic Style. Ideally, the rules should be clear and complete enough that a program could rewrite the code (though it's unlikely you'll ever code one ;) )
For the naming convention, I would try to make class/types easily distinguished from variables/attributes.
It is also in this category that I classify the "measures" like:
- prefer short to long methods: it's usually difficult to agree on what long is
- prefer early return/continue/break to reduce indentation
And as a final word, there is one item that is rarely, if ever, discussed in Coding Standards, perhaps because it's particular to each application: code organization. The architectural issue is perhaps the most outstanding issue, screw up on the initial design and you'll be plagued by it years from now. You should perhaps add a section for basic file handling: public/private headers, dependency management, separation of concern, interfacing with other systems or libraries...
But those are nothing if they are not actually applied and enforced.
Any violation should be brought up during code reviews, and no code review should be okay if a violation is outstanding:
- fix the code to match the rule
- fix the rule so that the code doesn't stand out any longer
Obviously, changing a rule means getting the "go ahead" from the leaders.