Subsections

2.9 Layout of code

One simple, but important way that code can be improved for a human audience is to format the code so that it is easy to read and easy to navigate.

Consider the following two code chunks. They contain identical HTML code, as far as the computer's understanding is concerned, but they are vastly different in terms of how easy it is for a human reader to comprehend them. Try finding the “title” part of the code. Even without knowing anything about HTML, this is a ridiculously easy task in the second layout, and annoyingly difficult in the first.

<html><head><title>A Minimal HTML 
Document</title></head><body>
Your content goes here!</body>

<html>
    <head>
        <title>A Minimal HTML Document</title>
    </head>
    <body>
        Your content goes here!
    </body>

This demonstrates the basic idea behind laying out code. The changes are entirely cosmetic, but they are extremely effective. It also demonstrates one important layout technique: indenting.

2.9.1 Indenting code

The idea of indenting code is to expose the structure of the code. What “structure” means will vary between computer languages, but in most cases the language will contain blocks of the form:

BEGIN
    body line
    body line
END

As demonstrated, a simple indenting rule is always to indent the “body” of a block of code. This is very easy to demonstrate using HTML, where code blocks are formed by start and end tags. Here is a simple example:

<head>
    <title>A Minimal HTML Document</title>
</head>

The amount of indenting is a personal choice. The examples here have used 4 spaces, but 2 spaces or even 8 space are also common. Whatever indentation is chosen, it is essential that the indenting rule is applied consistently, especially when more than one person might modify the same piece of code.

Exposing structure of code by indenting is important because it makes it easy for someone reading the code to navigate within the code. It is easy to identify different parts of the code, which makes it easier to see what the code is doing.

Another useful result of indenting is that it provides a basic check on the correctness of code. Look again at the simple HTML code example. Does anything look wrong?

<html>
    <head>
        <title>A Minimal HTML Document</title>
    </head>
    <body>
        Your content goes here!
    </body>

Even without knowing anything about HTML, the lack of symmetry in the layout suggests that there is something missing at the bottom of this piece of code. In this case, indenting has alerted us to the fact that there is no end </html> tag.

2.9.2 Long lines of code

Another situation where indenting should be applied is when a line of computer code becomes very long. It is a bad idea to have a single line of code that is wider than the screen on which the code is being viewed (so that we have to scroll across the window to see all of the code). When this happens, the code should be split across several lines (most computer languages do not notice the difference). Here is an example of a line of HTML code that is too long.

<table border="1" bgcolor="#CCCCCC" summary="A simple border for numerical data">

Here is the code again, split across several lines. It is important that the subsequent lines of code are indented so that they are visually grouped with the first line.

<table border="1" bgcolor="#CCCCCC" 
       summary="A simple border for numerical data">

In the case of a long HTML element, a reasonable approach is to left-align the start of all attributes.

2.9.3 White space

White space refers to empty gaps in code, which are important for making code easy for humans to read. Wouldyouwriteinyournativelanguagewithoutputtingspacesbetweenthewords?

Indenting is a form of white space that always appears at the start of a line, but white space is effective within and between lines of code as well. For example, the following code is too dense and therfore is difficult to read.

<table border="1"width="100%"bgcolor="#CCCCCC">

This modification of the code, with extra spaces, is much easier on the eye.

<table border="1" width="100%" bgcolor="#CCCCCC">

The two code chunks below demonstrate the usefulness of blank lines between code blocks to help expose the structure, particularly in large pieces of code.

$\usebox{\tmpbox}$ $\usebox{\tmpbox}$

Again, exactly when to use spaces or blank lines depends on personal style.

Paul Murrell

This document is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 License.