Graphlet Coding Standards

Documentation

Document Your Source Code

In-program documentation should provide the following information:

A short description of the module.
Document all non obvious code. Any peculiarities (e.g. system dependencies) should be noted in the header.

Long and descriptive names are even more important than comments. In many cases comments can be omitted if the name says it all.

Use English

All documentation must be in English. Furthermore, all names used in the programs must be in English. This is necessary because your code might be used by many people from all over the world. More than 90% of them do not speak german, but all of them are capable of understanding english. Imagine you try to understand a program that is documented in elvish. Do also consider spel checking your documentation.

Use HTML for external documentation

All external (that is, all documentation outside the source code) must be done using HTML. LaTeX is not appropriate because most Windows users do not have LaTeX.

Document Header

All files in the Graphlet distribution should contain a header which describes the file. A sample header for C++ files is shown in the following example. Other file formats should copy and adapt this header.

The header should contain a short description of the file.
The fields enclosed in $Tag: ...$ are used by the CVS version control system. Do not enter information in these fields, they will be overwritten as soon as the file is checked in. See also the Section on version control systems.
Header templates for most common file formats can be found in the directory lib/graphlet/etc in the graphlet distribution.

Here is a sample template header for a Graphlet file:

//
// filename
//
// The description of filename goes HERE.
//
//------------------------------------------
//
// $Source: /home/br/CVS/graphlet/doc/Standards-General.tex,v $
// $Author: himsolt $
// $Revision: 1.1.1.1 $
// $Date: 1998/08/27 17:19:01 $
// $Locker:  $
// $State: Exp $
//
//------------------------------------------
//
// (C) University of Passau 1995-1999, graphlet Project
//

Editor

On UNIX machines, we recommend to use the emacs or xemacs editor. A customization for the cc mode in emacs or xemacs is available in the Graphlet distribution in lib/graphlet/etc/cc-mode.el. This mode helps you to format your C and C++ code properly. To use this customization, insert

(load (expand-file-name "graphlet-dir/lib/graphlet/etc/cc-mode"))

in your emacs startup file (usually .emacs or .emacslocal), where graphlet-dir is the directory where your copy of Graphlet resides (typically ~/graphlet), or the directory where Graphlet is installed.

Note: Do not copy the file cc-mode.el into your directory. This file gets occassional updates which you would loose then.

External Tools

We recommend to use the following external tools:

GNU make: Use GNU make for makefiles. GNU make's extended features are admittedly incompatible with other make systems, but what counts is the fact that GNU make is the same on all platforms.
We decided not to use GNU autoconfigure or other preprocessor based tools, since automatically generated files are usually hard to debug. Instead, use GNU make's if constructs.
Tcl, perl: Use Tcl and perl for scripts. They are external tools, but Tcl is ok since Graphlet needs Tcl anyway. Perl is installed on most systems and provides a highly portable alternative to sh, csh, bash, awk, sed and other UNIX tools. It is also available on most non-UNIX platforms.
Others: If you have to use additional external tools, make sure that they are available for all major platforms, preferrably UNIX and MS Windows. They should be easy to install and available at no cost. If this is not the case, the tool should only be used for optional features.
In any case, check it with Graphlet maintainers if you want to include your code in the distribution.

Filenames

File names must adhere the following conventions:

File names should be descriptive.
Use the following endings in your program:
- .c for C code,
- .cpp for C++ code,
- .h for C and C++ header files,
- .tcl for Tcl code,
- .perl for Perl scripts,
- .html for html files.
- .css for cascading style sheet files.
Graphlet's GNUMakefiles provide default suffix rules which rely on proper use of the above endings.
Note: The ending .C for C++ code will not work well with file systems that make no distinction between upper and lower case names, and is therefore discouraged. The ending .cpp for C++ files was chosen because most compilers accept it without problems.
Use the name GNUmakefile for makefiles. This makes sure that other make systems (which are incompatible with GNU make) use do not recognize the file and issue an error message that no Makefile is available.

Line Width

The maximum line with of program code must not exceed 79 characters so that emacs and other editors can be used without adjusting the window width. This makes sure that the code can be

easily printed,
edited in a standard size window (even on an ASCII terminal),
easily inserted into a text document.

Documentation should not use more than 65 characters per line.

The only exception from the above width restrictions are files in special formats where the syntax demands lines longer than the above limit, or where long lines are highly common, for example X11 resource files.

Notes:

In emacs, you can help that text (not program code!) does not exceed a width of 79 characters per line by inserting
(setq-default fill-column 79)
in your emacs startup file (usually .emacs or .emacslocal). To use this, type your text and use the fill command (default shortcut M-q) to format the text.
Hint for emacs experts: auto-fill-mode may be useful. Type C-h f RET auto-fill-mode in emacs for more information.

Portability

The following guidelines must be followed to ensure portability:

Minimize the amount of non portable code.: Almost all programs can be written using only portable code. If possible, use Tcl code for system dependend code. Tcl provides portable interfaces to many low-level functions.
Identify non portable code: Put non portable code into a separate module and mention this in the documentation.
No compiler specific features: Avoid compiler specific or other non standard features at all costs.
Test with different compilers and on different platforms: Test your code on several compilers and on different operating systems. This will help you to find bugs easier, and make sure that it is more likely that your code works with the next compiler generation.

Readability

Your code must be easy to read. Here are some hints how to achieve that:

Consistency: Your code should have a consistent ``look-and-feel'', which should ideally be the same as used in the Graphlet core. The Graphlet core is the graphlet system without algorithms, that is src/gt_base and src/gt_tcl. All examples in the Graphlet documentation use this style.
Indentation: Use indentation to outline the structure of your program. Graphlet generally uses 4 spaces for indentation levels.
Note: Do not redefine the tabulator width to 4 spaces for indentation. This will only work with your editor, and results in badly formatted code when combined with others.
Long Names: Use long and descriptive names. This can replace lots of documentation. Use short names only if the meaning is obvious. For example, it is common to use x and y for coordinates or i, j, k for running indices. However, it is not a good idea to use the name h, help or a1, a2, ... for auxiliary variables.
Use separators: Use blank lines as separators. For example, add a blank line before and after an if, while or for block, and add at least 2 blank lines between functions. Add more blank lines, or even comments if suitable to show the large scale structure of your program.
Write simple code: Generally, avoid overly complex constructions. Split them into smaller units. The exception is code which is critical for optimization and you know (e.g. from profiling) the compiler cannot handle this.
Note: Your supervisor might ask you to prove that you really need too complex code, and might ask you to remove it if your arguments are not convincing.

Standards

Make your code conform to standards (keywords: ANSI, Posix). If you use de facto standards, make sure that they are really as common as you think. Be careful with functions which are not marked as standard.

Version Control

We strongly recommend to use a version control tool like RCS or CVS. CVS is mandatory for development in Passau. Graphlet's standard headers already provide the neccessary entries for CVS headers.

CVS and emacs

Recent versions of emacs and xemacs automatically recognize CVS and show the current versions in the modeline.

Emacs won't make backup files if version control is active. Put the following line in your emacs startup file (.emacs or .emacslocal) to change this behavior:

(setq vc-make-backup-files t)

We recommend to use this configuration as the backup copy will almost always be more recent than your latest committed version.

Local Configuration (Passau)

The local configuration at the University of Passau (specific to the computers at the chair of theoretical computer science) is as follows:

The CVS root is at /home/br/CVS. You need to set the environment variable CVSROOT to that location. To do that, add the line
export CVSROOT=/home/br/CVS

to your .bashlocal file.
|
The CVS module for GTL is called GTL. To checkout the source code, type
cvs checkout GTL

This will create a directory named GTL.
The CVS module for Graphlet is called graphlet. To check the source code out, type
cvs checkout graphlet

This will create a directory named graphlet.
Documentation for CVS is available as emacs info files. To read the documentation, start emacs and type
C-h i m cvs RET

to get to the CVS documentation.

Graphlet | Coding Standards