One of the continuing question in the software industry
is "How to you improve software quality?" Actually the
question at most organizations is "How can we improve our
software so that it merely lousy, instead of really
The first step is to define a common programming style
for all programmers. Many companies have a style committee
or a tiger team devoted to defining programming style.
The committee method of defining style doesn't work.
The style manuals tend to be large, unreadable and impractical.
You can solve 90% of the style problem with some simple
style rules. They don't have to be complex, in fact
they can easily fit on one page. The shorter, the better.
It makes it much easier for programmers to follow the style
guidelines, when it's possible to read them.
Here are my suggestions for a style sheet.
Choose a common naming style. Most everyone agrees that
constants should be uppercase words, separated by underscores
THIS_IS_A_CONSTANT). Variables can be:
Lower case, separated by "_" (
Initial Caps (
Don't try anything more complex than this. Complex rules are
hard to follow and difficult to understand. Just look at the
rules governing the Motif API for an example of how not to do
Use standard set of prefixes and suffixes for your variable names.
Global variables and functions may be prefixed with
an abbreviation of their module name. If you prefix
one variable, your must prefix them all.
Variable names should consist of whole words, no abbreviations.
It's hard to debug a counting program when people spell
Concerning Microsoft notation (aka. Hungarian Notation) which
uses a series of letters at the beginning of a variable to denote
type: You should (choose one) a) laugh, b) gag, and then
ignore this unnovation.
All variables declarations should have a comment explaining
what they do.
Variable names should be one, two, or three words. In no cases
should a single or double character variable name be allowed. (Unless
the full name is one or two characters such as "pi.")
Choose a common indentation size. Studies at Rice University
have shown that 4 spaces is best, but it doesn't matter that
much as long as you're consistent.
Choose a consistent placement policy for the curly braces.
Feel free to choose any of the placement policies championed
by the curly brace fanatics. Which one you choose is not so
important is consistency.
About the time the indent causes your program to run into the
right side of the screen, consider breaking your code into
two simpler functions.
Precede all functions by a comment block explaining them.
Make this comment block stand out.
Functions should be at most two or three pages long. Anything
longer should probably be split up into smaller, simpler functions.
Each case statement in a switch should end with
"break" or the
/* fall through */. The
/* fall through */ lets people know
that you didn't forget a
14. Remember the tortoise and the hair. Slow and stead beats complex,
wonderful, and fast every time. Program for reliability and readability
unless your absolutely positively sure that the speed of your code
is critical to it's operation.
When designing C++ classes, remember the big four: The default
constructor, the copy constructor, the destructor, and the
assignment operator. If you want to use the C++ defaults for these
member functions, document that in the code.
The most important rule of all: If any of the above rules keep
you from making a clear, easily to understand, readable, reliable
program, discard them. Be prepared to defend your decision, but
don't let the rules get in the way of doing what's right.
These rules don't cover everything, but there simple and
easily remembered. They are what a programmer can remember
and follow. And getting everyone in your project to follow
the same rules will tremendously improve the productivity
and reliability of the software written by your team.