Introduction

Amongst programmers, the most dangerous topic for a discussion is probably that of style and coding conventions. In forums, this subject is always a good candidate to start flames and, with luck, a good old religion war. This is very true in general, but even more so for experienced programmers who have their own habits, habits that have been acquired over the years.

Because of that, it is always difficult to introduce a new set of rules and conventions into a programmers team. In my experience, rules are often fought against and it may take a long time before everyone agrees to use them, let alone be happy with them.

Yet, good rules and conventions are necessary because they can really help writing better code, code that is more readable and has less bugs.

This document is an attempt to find a solution to the above problem. It lists a set of rules, yes, but it also tries to explain the reasons behind every and each stated rule. Moreover, it contains very few rules and a great deal more recommendations, which can be handled more loosely. This approach tries to establish a set of conventions that can be discussed, modified and eventually agreed upon in a natural way, not by enforcement.

Still, I don't see this as a work on coding conventions, but rather on good programming practices. As such, it is targeted to all programming languages, even if practically all examples are written in C or C++.

At times, it may happen that a rule must be broken: experience will suggest the few cases where the exception is more proper than the rule. However, all exceptions must be clearly and carefully documented, both for current reviews and for future maintainers.

I have spent countless hours on this work, and I am publishing it in the hope that someone finds it useful. I am always open to suggestions, comments, error reports and constructive criticism that can help improve the content, just send a mail to: dev@ascotti.org.