Commenting conventions.

Introduction.

This documents describes how C-- source files for the Migration on Request tool should be commented. It is important to follow these conventions for a number of reasons:

• i It aids readability, since it is easier to follow the flow of the source file and to find particular sections.
• ii It will assist any automated documentation tool, which I (pjm) intend to write at some point.
• iii It encourages comments to be written at the same time as the program, rather than at the end!

The conventions are fairly straightforward; in case of doubt look at some of the existing source files, and feel free to cut and paste.

Header files.

Header block.

There must be a header block at the start of the file. It should indicate the filename, description, author(s) and history. Here is an example of how the header block should be constructed:

  
     /*
      * filename.ext
      *
      * Description:
      *   A brief description of the file.
      *
      * Author(s):
      *   Name of the author. Possibly contact details.
      *
      * History:
      *   DD/MM/YYYY  Description of work done.
      *               ...
      */

Structure definitions.

Comments should be placed before the struct-ure explaining the name of the structure and what it is used for. These comments should use SIX asterisks. Example:

 
     /******
       StructObject
       This holds some information about this and that.
     ******/
     
     struct StructObject
     {
       int x;  /* the first very important number */
       int y;  /* this number is not so important */
     };

Public functions for struct-objects.

These should be prefixed by a FOUR asterisk comment:

     /****
       Struct-object name
       Public functions
     ****/

Sub headings

Functions can be grouped under sub headings using THREE asterisk comments:

 
     /*** Standard struct-object functions ***/

Function descriptions

Descriptions of the functions themselves should be directly before the function definition, and within TWO asterisk comments.

     /** Takes a number and applies it to the object. **/
     void StructObject_applyNumber(struct StructObject* s, int x);

Private functions for struct-objects.

These should follow the same principle as the public functions.

Implementation files

Header block

This should be of the same style as the header block in header files (see section 1.1). It should always be present.

Function definitions

Each function should, after its name and type declaration, but before the opening { brace, describe in reasonable detail what it does, the parameters it takes in, passes out, and the return value.

     Example:
     --------
     
     int StrObject_calculate(const struct StrObject* s, int a, int b, int* c)
     /*
      * Takes two numbers and performs a*x + b/y.  The result is stored in c.
      * If divison by zero occurs, c is left unaltered.
      * Returns 0 if success, or 1 if division by zero.
      *
      * IN:      s: StrObject containing x and y values
      *          a: first value
      *          b: second value
      * OUT:     c: result of a*x + b/y
      * RETURNS: 0 if success, 1 if division by zero
      */
     {
       if (s->y == 0)
         return 1;
     
       *c = a * s->x + b / s->y;
       return 0;
     }

Sub headings

Functions may be organised under different section headings by using THREE asterisk comments:

 
     /*** Selectors ***/

General.

For consistency, do not use // style comments, stick to the /* */ variety. Ensure that there are spaces around the /* and */ to aid the automated documentation tool.

Do not nest comments.

In critical situations, during heavy debug work, it is possible to use #ifdef / #endif precompiler directives. These are much easier to use when commenting out large sections of heavily commented code. Please ensure that these are removed before release, since they are not part of the C-- specification.

Back to developer's page