Writing Quality Software: A Primer - Consistent and Readable Code Format (Page 3 of 7 )
Have you ever poked around in someone else's code, only to find the entire document left aligned? Very readable? No, of course not. Learning effective code formatting makes the job of reading your code exponentially easier.
For example, take this block of code, a classic example of bad coding ethic:
for ($x=0;$x<=50;$x++)
{
echo States[$x];
$Inc .= $Incrementor;
if (($Inc == 9) || ($Inc == 10))
{
echo "Execute this line of code";
}
}
The above code block is not especially readable; from a glance, it is not immediately clear where control structures begin, which happen to be perfect places to indent. Control structures include for loops, if statements and select/case blocks. Let's try re-writing this piece of code, in a style more readable.
for ($x=0;$x<=50;$x++)
{
echo States[$x];
$Inc .= $Incrementor;
if (($Inc == 9) || ($Inc == 10))
{
echo "Execute this line of code";
}
}
More readable? Yes, I think so. Even at a quick glance, we can clearly determine where control structures are coded, because we have indented our code and spaced it accordingly. One of the first marks of a quality software application is a properly formatted source code document. Not only can we read our logic, we also clearly see our logic.
So, where should you indent your code? A good rule to keep in mind is always indent code within control structures, like loops (for, while, do...while), and within if statements. If you are using a language such as Pascal, indent variable/constant definition blocks and within Begin/End code structures. Further, always indent code within functions or procedures.
Also notice our use of white space. Developers are often afraid of white space because of increased program size; this is a mistake, however. Use white space liberally to give your code room to breathe. After all, you would not think of writing a business report without spacing between your words and paragraphs, right? Code follows similar logic.
I chose to surround my if statement with squiggly braces {} in the above code example, although I was technically not required to because my if statement only contained a single line of code. When in doubt, certainly use these squiggle braces, but consider using them anyway, even if you know they are not needed. These braces create a grouping effect that suggests particular code belongs together and, in the case of our if statement, execute only when that statement returns true.
Be careful about utilizing modern programming languages' ability to interpret multiple commands on a single line. When reading through code fast, we naturally assume each statement is afforded its own line. When two commands rest on the same line, it is easy for us to miss that second command. For the sake of clarity and readability, give each command its own line.
If you use comments in your code, be sure to indent those comments along with the indented source code. This again suggests grouping, and makes it clear which comments describe which commands. We will look at comments at more depth later in this article.
Many corporations put teeth into source code formatting, often insisting on a collection of strict guidelines for software construction. A set of guidelines that all internal programmers follow makes code inspections and unit testing easier to digest.
To wrap up, here's what you should have learned:
- Always indent code within control structures
- Utilize the benefits of white spaces
- Use squiggly braces, even if not required
- Place each command on a separate line
- Indent comments with appropriate code
Next: Naming Conventions >>
More Practices Articles
More By Steve Adcock
/ 23 
