Introduction
Code layout is important because it will have an impact on future maintenance of the source code. It is a trade off between ease of reading and ease of code creation - it may take slightly longer to write code that is laid out correctly, but it will help when coming back to the code if it is easy to read and digest.
Of course, we can say exactly the same about comments, which are also covered in an article How to Comment Computer Programs. The idea is to be able to efficiently maintain code, and understand what each individual piece does just by reading it through once.
Language Neutrality
It really does not matter what language is being used. The principles of code layout are still the same, because every procedural language shares the same basic set of possible code constructs:
- Decisions
- Loops
- Functions / Procedures
- Complex data types (records, structures, etc.)
- Data types, variables and arrays
- Etc.
Many of these constructs require that code is contained within scope delimiters, which may vary between languages. Whether it is a BASIC Begin...End delimiting pair, or opening and closing braces ('{' and '}') common to C and C styled languages (from Java to Perl), code inside should be considered as a block, and formatted accordingly.
Code Indentation
The key to good code layout is the level of indentation that is applied to these code blocks, as well as the position of the scope delimiters. Let us look at three very different examples. Firstly, consider the usual layout for a BBC BASIC IF-THEN-ELSE statement:
IF VariableValue THEN PRINT "Lower" ELSE PRINT "Higher"
Since it is all on one line, no indentation is possible, and no delimiters required. It is considered to be less readable, however, than the second example, in Visual Basic:
MsgBox("Lower", vbOkOnly)
Else
MsgBox("Higher", vbOkOnly)
EndIf
The above allows for indentation, and places the statement over several lines, making it much easier to read. Finally, we have the C styled variant:
printf("Lower");
}
else {
printf ("Higher");
}
Now, this is 'traditional' indentation and layout, which is reasonably compact. Note that the braces are optional in the above example, because each clause only has one code statement - we'll assume for now that the printf line is just one of a few. Many programmers (C, C++, Java, Perl, etc.) prefer a slightly adapted layout:
{
printf("Lower");
}
else
{
printf("Higher");
}
This is properly indented, and looks cleaner. It is, however, less compact than the previous example. It has one major advantage, though, in that it allows for more precise commenting.
Code Comment Placement
While we are not covering what should constitute a code comment, we do need to say a few words about readability and placement because it forms part of the code layout. We mentioned above that the less compact form of indentation in C styled languages was garnering favor amongst programmers, and part of the reason is because it allows excellent code comment placement.
For example:
{ // Describe the impact of this decision here
printf("Lower");
}
else // Describe the actual else decision
{ // Describe the impact of the else clause
printf("Higher");
}
In the above example, we have exaggerated the commenting a little, to show where they could be placed. Good comments will describe the intent of the code statement, and then the impact of each possible evaluation. This is much more difficult to do, because there is less space available, if we write code using the compact layout:
printf("Lower");
}
else { // Impact and/or description
printf ("Higher");
}
It is worth noting that comments could be inserted above the code statements, but is this more unreadable, in this author's opinion.
Indent Size
Finally, we need to discuss actual indent size. Let us begin by ruling out the use of tabs. We are not working in a word processing environment, we are programming. As such, special characters like tabs will always need to be translated to spaces, so let us just use spaces.
Furthermore, most code is viewed in a fixed pitch format, not variable pitch. As such a space takes as much width as any other character, and therefore, five spaces of indent (the usual 'tab' replacement) is far too much. Two space characters per indent are ample.
This also presents an easy-to-type tradeoff between readability and speed, for those not using an automatically indenting programming tool. As a final thought - code layout is made much easier if a good editor is being used; and when choosing one, make sure that it will have enough 'knowledge' of the language to automatically format according to best practice rules, of which this article forms a part.
