Coding Conventions:
Introduction

Standardization is Important
Interpretation
Standards Enforcement
Credits

Standardization is Important

It helps if the standard annoys everyone in some way so everyone feels they are on the same playing field. The proposal here has evolved over many years and projects, and literally a total of many weeks spent arguing. It is no particular person's style and is certainly open to debate.

So why standardize at all?

Good Points

When a project tries to adhere to common standards a few good things happen:

programmers can go into any code and figure out what's going on
new people can get up to speed quickly
people new to C++ are spared the need to develop a personal style and defend it to the death
people new to C++ are spared making the same mistakes over and over again
people make fewer mistakes in consistent environments
programmers have a common enemy :-)

Bad Points

Now the bad:

the standard is usually stupid because it was made by someone who doesn't understand C++
the standard is usually stupid because it's not what I do
standards reduce creativity
standards are unnecessary as long as people are consistent
standards enforce too much structure
people ignore standards anyway

Discussion

The experience of many projects leads to the conclusion that using coding standards makes the project go smoother. Are standards necessary for success? Of course not. But they help, and we need all the help we can get! Be honest, most arguments against a particular standard come from the ego. Few decisions in a reasonable standard really can be said to be technically deficient, just matters of taste. So be flexible, control the ego a bit, and remember any project is fundamentally a team effort.

Interpretation

The use of the word shall or must in this document implies compliance with the standard is mandatory.

The absence of the word shall or must constitutes a suggestion and not a mandatory standard. In particular, the word should does not mean mandatory compliance is necessary.

Standards Enforcement

First, any serious concerns about the standard should be brought up and worked out within the group. Maybe the standard is not quite appropriate for your situation, it may have over looked important issues, or maybe someone in power vehemently disagrees with certain issues :-)

In any case, once finalized hopefully people will play the adult and understand that this standard is reasonable, and has been found reasonable by many other programmers, and therefore is worthy of being followed even with personal reservations.

Failing willing cooperation it can be made a requirement that this standard must be followed to pass a code inspection.

Failing that the only solution is a massive tickling party on the offending party.

Credits

Justifications, ideas and sometimes huge blocks of text were taken from the following documents to varying degrees:

C++ Coding Standard

tmh@possibility.com

Coding Conventions: Introduction

Table of Contents