The source code of a program should be easily readable and understandable, not only by the author him/herself, but in particular by other software developers. Thus stick to common style practices (don't invent your own ones) and, whatever style you choose, be consistent in your use of that style.

Some general recommendations are given below (see the source code examples of this course which more or less follow these guidelines).

  • Use English as the language of identifiers and comments.
Nowadays it is nonsense to believe that only a German-speaking developer will (have to) read and work with your source code.

  • Do not write lines longer than 80 characters.
Longer lines are hard to read and may give problems with other editors.

  • Use inform indenting.
Use 2 or 3 spaces per indentation level, do not use tabulators because they are rendered differently in different settings.

while (i < j)
{
  if (i <= k)
    i = i+1;
  else
  {
    i = 0;
    j = j-1;
  }
}
  • Choose speaking names for your identifiers.
    • Variables: nouns, potentially accompanied by adjectives (except perhaps for loop indices which can be named i,j,...)
name, number, lastNode
    • Functions with an effect: commands
print(s), printHeader(t), processFile(f)
    • Functions that compute results without side effects: nouns
y = factorial(x), z = min(x,y)
    • Types/classes: nouns representing kinds of objects (often capitalized to distinguish them from variables)
Nat, Record, File
  • Write a comment for every global variable (a variable declared on the name space or class level).
And also for those variables local to a function where additional information seems appropriate.

int length; // number of elements on the stack

// pointer to the element table
// (null, if length == 0)
int *table;
  • Write a comment header for every file.
The header should explains the overall content of the file and gives information about its development and ownership.

// ---------------------------------------------------------
// File.h
// class File for file manipulation and associated operations.
//
// Author: Wolfgang Schreiner <Wolfgang.Schreiner@risc.jku.at>
// Last Modification: 10.2.2009
//
// (c) Wolfgang Schreiner, 2009
// ----------------------------------------------------------
  • Write a comment header for every class declaration.
The header should explain the overall purpose of the class.

// -----------------------------------------------------------
// IntStack: a stack of integer values.
// A stack is represented by a dynamically expanded array,
// i.e. it can contain an arbitrary number of elements.
// -----------------------------------------------------------
class Stack { ... }
  • Write a comment header for every function declaration and definition.
The header should specify the externally visible behavior (not the internal implementation) of the function such that other people can use the function without looking into the source of the implementation. Such a specification in general consists of

    • an input condition: what must be true for the values of parameters and global variables such that the function may be called.
    • an output condition: what is true for the values of parameters and global variables after the function has been called.
    • an effect description: any visible behavior that is not adequately covered by the output condition.
// -----------------------------------------------------------
// e = stack.popAndPrint()
// e is popped from the stack and printed.
//
// Input condition: the stack is not empty
//   stack.length() > 0
// Output condition: e is the element on the top of the old stack
//   e == old(stack.top())
// The new stack is the old stack with the top element removed:
//   stack.length() == old(stack.length()-1)
//   stack.at(i) == old(stack.at(i+1)) for all 0 <= i < stack.length
// Effect: prints e on std::cout.
// -----------------------------------------------------------
int IntStack::popAndPrint() { ... }