About This Book
We have set out the following design goals for this book:
Short is better than long:
Huge coding standards tend to be ignored; short ones get read and used. Long Items tend to be skimmed; short ones get read and used.
Each Item must be noncontroversial:
This book exists to document widely agreed-upon standards, not to invent them. If a guideline is not appropriate in all cases, it will be presented that way (e.g., "Consider X…" instead of "Do X…") and we will note commonly accepted exceptions.
Each Item must be authoritative:
The guidelines in this book are backed up by references to existing published works. This book is intended to also provide an index into the C++ literature.
Each Item must need saying:
We chose not to define new guidelines for things that you'll do anyway, that are already enforced or detected by the compiler, or that are already covered under other Items. Example:
"Don't return a pointer/reference to an automatic variable" is a good guideline, but we chose not to include it in this book because all of the compilers we tried already emit a warning for this, and so the issue is already covered under the broader Item 1, "Compile cleanly at high warning levels." Example:
"Use an editor (or compiler, or debugger)" is a good guideline, but of course you'll use those tools anyway without being told; instead, we spend two of our first four Items on "Use an automated build system" and "Use a version control system." Example:
"Don't abuse goto" is a great Item, but in our experience programmers universally know this, and it doesn't need saying any more.
Each Item is laid out as follows:
Item title:
The simplest meaningful sound bite we could come up with as a mnemonic for the rule.
Summary:
The most essential points, briefly stated.
Discussion:
An extended explanation of the guideline. This often includes brief rationale, but remember that the bulk of the rationale is intentionally left in the References.
Examples (if applicable):
Examples that demonstrate a rule or make it memorable.
Exceptions (if applicable):
Any (and usually rare) cases when a rule doesn't apply. But beware the trap of being too quick to think: "Oh, I'm special; this doesn't apply in my situation"that rationalization is common, and commonly wrong.
References:
See these parts of the C++ literature for the full details and analysis.
In each section, we chose to nominate a "most valuable Item." Often, it's the first Item in a section, because we tried to put important Items up front in each part; but other times an important Item couldn't be put up front, for flow or readability reasons, and we felt the need to call it out for special attention in this way.
|