Home arrow Practices arrow Page 3 - Writing Quality Software: A Primer

Consistent and Readable Code Format - Practices

development prracticesOkay, so you have a respectable handle on syntax, and you are proud of yourself for getting that far. And, truth be told, you should be. But, knowing syntax is not the same as mastering syntax in such a way that builds quick, efficient web software. This article takes a look at not just writing software, but writing quality software.

  1. Writing Quality Software: A Primer
  2. Some General Quality Issues
  3. Consistent and Readable Code Format
  4. Naming Conventions
  5. Appropriately Commenting Your Code
  6. Unit Testing
  7. System Testing
By: Steve Adcock
Rating: starstarstarstarstar / 24
December 15, 2003

print this article


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

>>> More Practices Articles          >>> More By Steve Adcock

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: