Some Techniques for Writing Clean Code

Document Your Code

Remember, if your code isn't worth documenting then it isn't worth keeping (Nagler, 1995). When you apply the documentation standards and guidelines proposed here you can greatly enhance the quality of your code.

Paragraph/Indent Your Code

One way to improve the readability of a member function is to paragraph it, or in other words indent your code within the scope of a code block. Any code within braces, the { and } characters, forms a block. The basic idea is that the code within a block should be uniformly indented one unit (we recommend that one unit is 2 space characters).

To ensure consistency, start your function and class declarations in column 1 (NPS, 1996). The convention appears to be that the open brace is to be put on the same line with the owner of the block and that the closing brace should be on the same level.

Use Whitespace in Your Code

A few blank lines or spaces, called whitespace, added to your code can help to make it much more readable by breaking it up into small, easy-to-digest sections (NPS, 1996; Ambler, 1998). The Vision 2000 team (1996) suggests using a single blank line to separate logical groups of code, such as control structures, with two blank lines to separate member function definitions. Without whitespace it is very difficult to read and to understand. In the code below notice how the readability second version of the code is improved by the addition of a blank line between setting the counter and the lines of code to calculate the grand total. Also notice how the addition of spaces around the operators and after the comma also increase the readability of the code. Small things, yes, but it can still make a big difference. Below is an example in PHP:

$counter=1;
$grandTotal=$invoice->total()+$this->getAmountDue();
$grandTotal=Discounter::discount($grandTotal,$this);

$counter = 1;
$grandTotal = $invoice->total() + $this->getAmountDue();
$grandTotal = Discounter::discount($grandTotal,$this);

Follow The Thirty-Second Rule

Another programmer should be able to look at your member function and be able to fully understand what it does, why it does it, and how it does it in less than 30 seconds. If he or she can't do that, then your code is too difficult to maintain and should be improved.

Related rule: If a function is more than a screen then it is probably too long.

Write Short, Single Command Lines

Your code should do one thing per line (Vision, 1996; Ambler, 1998). Whenever you attempt to do more than one thing on a single line of code you make it harder to understand. Why do this? We want to make our code easier to understand so that it is easier to maintain and enhance. Just like a function should do one thing and one thing only, you should only do one thing on a single line of code. Furthermore, you should write code that remains visible on the screen (Vision, 1996). A general rule is that you shouldn't have to scroll your editing window to the right to read the entire line of code, including code that uses endline comments.

Specify the Order of Operations

A really easy way to improve the understandability of your code is to use parenthesis, to specify the exact order of operations in your code (Nagler, 1995; Ambler, 1998). If I have to know the order of operations for a language to understand your source code then something is seriously wrong. This is mostly an issue for logical operators where you AND and OR several other comparisons together.

Organize Your Code Sensibly

Compare the two code examples presented below. The second one is easier to understand because the statements involving anObject have been placed together. The code still does the same thing, it's just a little easier to read now (note that if aCounter had been passed as a parameter in message3() then this change couldn't have been made). Below are PHP examples:

$anObject->message1();
$anObject->message2();
$aCounter = 1;
$anObject->message3();

$anObject->message1();
$anObject->message2();
$anObject->message3();

$aCounter = 1;

Place Constants on the Left Side of Comparisons

Consider the code examples below. Although they are both equivalent, at least on first inspection, the code on the first one compiles and the code on the second one does not. Why? Because the second if statement isn't doing a comparison, it's doing assignment – you can't assign a new value to a constant value such as 0. This can be a difficult bug to find in your code (at least without a sophisticated testing tool). By placing constants on the left side of comparisons you achieve the same effect and the compiler will catch it if you accidentally use assignment instead of comparison.

Look how they are in PHP:

if ( $something == 1 ) {
//...
}
if ( $x = 0 ) {
//...
}

if ( 1 == $something ) {
//...
}
if ( 0 = $x ) {
//...
}