Comments

General Regulations

1. An unneccessary comment wastes space – a missing comment wastes money!
2. Comments are written in the programmer's native language. This avoids information loss caused by the translation into a language the programmer isn't familiar with.
3. The topic tags in file, class und function headers (‘CREATED’, ‘DECLARATION’ etc.) have the significance of key words (even if not supported by the compiler) and are therefore always written in english.
4. (C++, Delphi) All line of a multi-line comment start with //.

// this is a multi-line comment,
// which illustrates the formatting
// of follow-up lines in C++ and Delphi.

5. (C, Pascal) The follow-up lines of a multi-line comment start with „//". Since the comment-terminating symbol „*/" (Pascal „*)", „}") has the character of a closing bracket, it is to be placed in the same column as the comment-starting symbol „/*" (Pascal „(*", „{").

C	Pascal
/* this is a multi-line comment, // which illustrates the formatting // of follow-up lines in C. */	(* this is a multi-line comment, // which illustrates the formatting // of follow-up lines Pascal. *)

This regulation makes it easier to define a single setting for updating C/C++/Pascal/Delphi files in the PVCS version control tool.

Programme Source

Comments are to insert into the source code (in seperate lines), if parts of functions or algorithms are difficult to understand.

Files

All files contain a descriptive header (sample description in italics):

//-------------------------------------------------------------------
// PROJECT      project name/subsystem name/…
// $Workfile$
// $Revision$
// PREFIX       prefix for public functions and variables
// DESCRIPTION  description of the module implemented in this file.
// CREATED      11-Dec-95, U.Sauerland - © ADVICE Softwarelösungen
// MODIFIED     20-Dec-95, U.Sauerland - © ADVICE Softwarelösungen
//                  Abstract of all changes, if they are made at
//                  different places in the file
//-------------------------------------------------------------------
// $Log$
//-------------------------------------------------------------------
// TABSIZE      4
// CHARSET      WINDOWS
//-------------------------------------------------------------------

Classes

Class declarations contain the following header:

//-------------------------------------------------------------------

class CConfiguration : public CSuperclass

// PATTERN      design pattern index and name
// PREFIX       type prefix abbreviation (e.g. cnf)
// DESCRIPTION  description of the class and its responsibilities
// CREATED      11-Dec-95, U.Sauerland - © ADVICE Softwarelösungen
// MODIFIED     20-Dec-95, U.Sauerland - © ADVICE Softwarelösungen
//                  description of the changes
{
    // declarations
};

Data Objects

Constants, global variables and types are commented in the same line or with an indented comment in the following line. The comment describes the purpose of the declared object.

#define MAX_ALERTS  42  // maximum number of possible alerts

typdef struct           // modelling of complex numbers
{
    float m_fReal;      // real part of the number
    float m_fImag;      // imaginary partof the number
} CComplex;

class CAirconditioner
{
    …
    private:
        float m_fMinimumHumidity;
            // relative humidity (in %), which
            // must not be passed below.
    …
}

Functions

Function Declarations

1. Function definitions are commented and formatted as follows:

//-------------------------------------------------------------------

class CKlasse

// Class comments

{
    …
    public: int Function
        (
            const int nParam1     // input parameter
            const int* pParam2    // output parameter
        )
        const                     // if neccessary (C++)
        throw (CException, …);    // if neccessary (C++)
        // DECLARATION      (polymorphic|override)    // optional
        //                    polymorphic: The function may be
        //                                 overridden polymorphically.
        //                    override   : The function overrides a
        //                                 polymorphic function of a
        //                                 superclass.
        // OPERATION TYPE   (constructor|destructor|modifier|selector)
        //                    constructor: constructor
        //                    destructor : destructor
        //                    modifier   : function changes member
        //                                 variables or the class' state
        //                                 vector (eg. by changing
        //                                 member variables that are
        //                                 referenced) respectively.
        //                    selector   : function doesn't change any
        //                                 member variable or the state
        //                                 vector respectively.
        //                    agent      : function performs operations
        //                                 for instances of other classes
        //                                 or the function is not a class
        //                                 member, but performs operations
        //                                 for objects.
        // PUBLICS USED       READ       : public data objects read only
        //                    READWRITE  : public data objects read only
        //                                 and written
        //                    WRITE      : public data objects written only
        // PRECONDITIONS      Assertions, which must be fulfilled before
        //                    the function is called.
        // DESCRIPTION        Descriptions of the function's tasks and algorithm
        //                    if neccessary (not trivial).
        // POSTCONDITIONS     Assertions, which are fulfilled after
        //                    the function was called.
        // RETURN VALUE       Description of the function's return value
        //                    (may be skipped for void functions).
};

Example:

//------------------------------------------------------------------

class CIntListe

// Class comments

{
    …
    public: int CIntList::Maximium
        (void)
        const
        throw (xmsg);
        // OPERATION TYPE   selector
        // PRECONDITIONS    the list must not be empty.
        // DESCRIPTION      Uses an iterator (defined in the classlib)
        //                  to browse the unsorted list.
        // POSTCONDITIONS   the list's length must not be changed
        //                  by the function
        // RETURN VALUE     Greatest value in the list.
    …
};

Function Definitions

The function definition's head list all changes of the function.

//------------------------------------------------------------------

int CClass::Function
    (void)
    // CREATED  18-Dec-95, U.Sauerland - © ADVICE Softwarelösungen
    // MODIFIED 12-Dec-96, U.Sauerland - © ADVICE Softwarelösungen
    //              Description of the change

Example:

//------------------------------------------------------------------

int CIntList::Maximium
    (void)
    const
    throw (xmsg)
    // CREATED  18-Dec-95, U.Sauerland - © ADVICE Softwarelösungen
    // MODIFIED 20-Dec-95, U.Sauerland - © ADVICE Softwarelösungen
    //              Sign error within compare fixed
    //          17-Apr-96, U.Sauerland - © ADVICE Softwarelösungen
    //              BORLAND-iterator-bug workaround
{
    REQUIRE(0 != Length());
        // The list is not empty..
    OLD(CIntListe);

    int nResult = -MAXINT;

    // Statements

    ENSURE(old.Laenge() == Laenge());
        // The function didn't change the list's length.
}

[back] | [next] | [TOC] | [Introduction] | [Layout] | [Programming Style Guide] | [Annexes]

Copyright © 1997-98 by Uwe Sauerland