Codierrichtlinien

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.

• Do not write lines longer than 80 characters.

• Use inform indenting.

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).

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.

// ---------------------------------------------------------
// 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.

// -----------------------------------------------------------
// 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.

• 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() { ... }