Good Programming Style


By Alex Allain

Consistency

One of the hallmarks of good programming style is consistency--the fewer surprises, the better. Consistency makes it easier to read the program primarily by reducing distractions. But it also helps guide the reader's eyes, for example, by being consistent about ordering functions or including files to simplify finding them in the future. It also makes it easier to deal with other style problems by making it easier for the reader to get used to them.

Clarity

Good style is about making your program clear and understandable as well as easily modifiable. When in doubt, choose the most easily understood technique for a problem. Remember that whatever you write, you will likely have to read at some point after you remember exactly what you were thinking. Do your future self a favor and be clear the first time.

Whitespace and Formatting

Whitespace can set things off and reduce the strain on the reader's eyes. Because the compiler ignores whitespace, you're free to place things anywhere you want and format it however you want. If you choose wisely, this can be a boon.

Whitespace comes in several forms, including indentation, how you put space around operators, how you lay out function signatures, and where you place arguments to functions. Of course, this is hardly everything covered by whitespace, but it should give you an idea of the many places whitespace can be used to improve readability.

Indentation

If you don't indent your code, you soon will. It's just a natural thing to do because it lets you use your eye to quickly pick out the flow of control or mistakes in that flow of control. The quick primer on indentation is that you should indent every block of code:
if ( true )
{
        // code block
}

Brace Styles

There are a variety of ways to indent code, and many of them are tied to where you place your braces. Some people prefer the style used above. Some people prefer the style below:
if ( true ) {
        // code block
}
Other styles include
if ( true )
        {
        // code block
        }
or even
if ( true )
        {
                // code block
        }
Any brace style you choose is up to you, although I'd recommend using the same brace style as everyone else working on your project. At any rate, there are arguments for each style. A good consideration is to use a brace style that allows you to put as much code on a screen at a time, but consistency with past practices is probably just as important.

Indentation Depth

How far you choose to indent is a matter of personal preference--in any case, it's usually best to choose an indentation size that's small enough to comfortably fit your code on one screen. I've found that any indentation width from 2 to 8 is reasonable and readable, although I've found that anything over four spaces for indentation can lead to lines that are too long.

In general, the best solution to dealing with lines that are too long is to reduce the complexity of the code or at least to pull out some functionality into separate functions. Doing so will reduce the number of levels of indentation and can make the code more readable (if it is done correctly).

Tabs vs. Spaces

There is something of an argument over whether to indent using tabs or spaces. Note that this is not the same as asking whether you indent with the spacebar or the tab--most people let their editors take care of that problem for them (or choose to have tabs expanded to spaces).

The real issue of tabs vs. spaces is what happens when someone else opens your code. Since you can set tabs to take up any number of columns, the person opening your code might not have the same tabstop width. This can play havoc with otherwise well-formatted code. Using only spaces fixes this problem because it will always display the same way for everyone.

Sometimes a decent code formatter, such as might be found in your text editor, can help mitigate this problem by reformatting the code. You can also play with your own tab settings to display the code correctly (although this is obviously annoying).

The best solution, if you do decide to use tabs, is to be very careful with what you use tabs for. The real problem, in fact, comes up when tabs are used not just for indentation but also as a quick way of moving four or eight characters to the right. For instance, let's look at the following code:
if ( a_long_case_number_one_stretching_across_most_of_the_screen &&
     a_long_case_number_two_also_stretching_across_most_of_the_screen )
{
    // code
}
If the second condition had been formatted using a tab with a four-space indent followed by a space, then when loaded with a tab-width of eight, it would look ugly:
if ( a_long_case_number_one_stretching_across_most_of_the_screen &&
         a_long_case_number_two_also_stretching_across_most_of_the_screen )
{
        // code
}
If spaces were used for the formatting, it would open correctly:
if ( a_long_case_number_one_stretching_across_most_of_the_screen &&
     a_long_case_number_two_also_stretching_across_most_of_the_screen )
{
        // code
}

Mis-Use of Whitespace

How much white space you use is, to some extent, a personal choice. There are some issues to be aware of. First, the more your whitespace helps emphasize the logic of your program, the better; you don't want your whitespace to "lie". This might not confuse the you-at-this-moment, but it can confuse the you-of-the-future or just someone else reading your code. What does lying look like?
if ( true )
        ++i;
        ++j;
The indentation makes it look like both statements get executed when the if statement executes--but that's not what actually happens. When you're tracking down a bug or syntax error in hundreds or thousands of lines of code, you may end up doing a visual scan instead of checking every line carefully. The easier you make it to scan the code and pick out salient details, the faster you can scan without making mistakes.
Related articles

Naming Conventions, and Names to Avoid

How you can write readable code, and why you should

Why Comment? How you can comment effectively!