Coding Conventions:
Introduction


Table of Contents

back to master Table of Contents

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:

Bad Points

Now the bad:

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: