Software Quality

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 rotten?"

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.

1. Choose a common naming style. Most everyone agrees that constants should be uppercase words, separated by underscores (THIS_IS_A_CONSTANT). Variables can be:
   1. Lower case, separated by "_" (this_is_a_var)
   2. Initial Caps (ThisIsAVar)

   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 it.

2. Use standard set of prefixes and suffixes for your variable names. For example:

   _ptr	Pointer variable
   n_	Number of

3. Global variables and functions may be prefixed with an abbreviation of their module name. If you prefix one variable, your must prefix them all.

4. Variable names should consist of whole words, no abbreviations. It's hard to debug a counting program when people spell "widget_count" as w_count, w_cnt, wdg_cnt, widget_cnt, widget_c, and w_c.

5. 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.

6. All variables declarations should have a comment explaining what they do.

7. 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.")

8. 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.

9. 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.

10. 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.

11. Precede all functions by a comment block explaining them. Make this comment block stand out.

12. Functions should be at most two or three pages long. Anything longer should probably be split up into smaller, simpler functions.

13. Each case statement in a switch should end with "break" or the comment /* fall through */. The /* fall through */ lets people know that you didn't forget a break.

14. 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.

15. 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.

16. 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.