Algorithms Design   |   C language   |   Index

Code layout

Computer programs must be understood by human beings as well as by computers.  This is why the layout of the source code of a program, i.e., the disposition of the code on a sheet of paper or on a computer screen, is so important.  The two main elements of the layout are

• the indentation of the lines,
• the spaces between the words (and other symbols) on a line.

The layout of a program should follow the same principles as the layout of any other kind of text (a book, a newpaper article, a blog, etc.).  It is easy to get used to produce a good layout.  With a little practice, the fingers of the programmer, dancing on the keyboard, will do the the right thing, leaving his mind free to take care of more important things.

A good layout

Here is a sample of a excellent layout. It follows the recommendations of many gurus and experienced programmers:

int func (int n, int v[])
{
   int i = 0;
   while (i < n) {
      if (v[i] != 0)  i = i + 1;
      else {
         for (int j = i + 1; j < n; ++j)  
            v[j-1] = v[j];
         n = n - 1;
      }
   }
   return n;
}

Notice how easy it is to check the matching of { and }. It is also easy to delete a line and to insert a new line, if needed, with the help of a text editor.

The sample code is set in monospaced font (i.e., a font in which all the characters have the same width). This is the ideal font for displaying code. Note how the characters of each line are vertically aligned with the characters of the previous line. Normal fonts (in which each character has a different width) are not good for displaying code, as the following example shows:

int func (int n, int v[])
{
    int i = 0;
    while (i < n) {
        if (v[i] != 0)  i = i + 1;
        else {
            for (int j = i + 1; j < n; ++j)
                v[j-1] = v[j];
            n = n - 1;
        }
    }
    return n;
}

A compact layout

The layout below uses less vertical space than the previous one. It is good for writing programs with pencil on paper (but not so good for making changes with a text editor). Correct indentation is essential in this layout.

int func (int n, int v[]) {
   int i = 0;
   while (i < n) {
      if (v[i] != 0)  i = i + 1;
      else {
         for (int j = i + 1; j < n; ++j)  
            v[j-1] = v[j];
         n = n - 1; }}
   return n; }

A bad layout example

The layout in the following example is very bad:

int func ( int n,int v[] ){
   int i=0;
   while(i < n){
      if (v[i] !=0) i=i +1;
      else
      {
         for(int j=i+1;j<n;++j )  
            v[j-1]=v[j];
         n =n- 1;
      }
   }
   return n;
}

This layout puts spaces in the wrong places and supresses spaces where they are really needed. The spaces in code are as important as the pauses in music! Moreover, the layout is inconsistent: it writes things first in one way and then in another.

Layout tips

When writing code, we should apply the same layout rules as books, newpaper articles, blogs, etc. Hence,

• use a space to separate each word from the next  (and remember that things like  =,  <=,  while,  if,  for,  etc. count as words);
• put a space after, but not before, each punctuation mark;
• put a space after, but não before, a  )  and a  } ;
• put a space before, but not after, a  (  and a  { .

The expression  while(j < n)  has the same unpleasant flavor as  whilej is smaller than n.  Therefore,

• never write  while(j < n)  in place of  while (j < n) ;
• never write  else{  in place of  else { ;
• do not write  for (i=1;i<n;++i)  in place of  for (i = 1; i < n; ++i) ;
• etc.

There are three notable exceptions to these rules:  write

• x->next  instead of  x -> next ,
• x[i]  instead of  x [i] ,
• x++  instead of  x ++ .

Moreover, it is usual to supress the spaces before and after the multiplication and division operators.  Hence, write  x*y  and  x/y  instead of  x * y  and  x / y  respectively.

I suggest you put a space between the name of a function and the following left parenthesis, even if this is contrary to traditional mathematical notation.  For example, I suggest you write

function (arg1, arg2)

instead of  function(arg1, arg2),  since the first layout is easier to read than the second.

Exercises

Layout tips

• Do not use long lines, neither in the code, nor in the comments.  Long lines are difficult to read and often do not fit the width of the sheet of paper or screen.  Seventy-odd characters per line is a good limit.  (By the way, see the Eighty Column Rule on Emacs Wiki.)
• Do not use tabulation (tab key) in the source code of your program.  To indent a line, use the appropriate number of spaces.  (See Tabs Are Evil on Emacs Wiki.)
• If you use tabs (despite the previous recommendation), use them only at the start of each line. And do it systematically: if one line begins with a tab then no line should begin with one or more spaces followed by a nonspace character.
• Some text editors automatically substitute tabs for long sequences of spaces. The substitution is imperceptible on the computer screen but tends to mess up the layout of the printed program. Configure your text editor to turn off the automatic substitution of tabs for spaces.
• Avoid superfluos nonspace characters in your code. In particular, avoid the parentheses that the rules of precedence between operators make redundant.
• There is nothing like a good manual layout. But in a squeeze you may resort to an app like astyle to fix the layout of your program.