Commenting Source Code

It is absolutely mandatory that each source file contains a reasonable number of comments. When a significant variable, data type, or function is declared, it must be accompanied with some descriptive information written in English. Every function prototype or body of it has to be preceeded by a short description of its purpose, algorithm (desirable; if it is too complex, provide a reference), what arguments it takes and what it returns.

Having said this, we will argue against excessive commenting: don't add a comment every time you do i++! It will actually make your code harder to read. Be sensible.

As of spring 2002, we have adopted the doxygen program to automatically generate source code documentation. This program scans the source code and looks for special codes which tell it to add the given comment block to the documentation list. The program is very fancy and can generate documentation in man, html, latex, and rtf formats. The file psi3.dox is the doxygen configuration file. The source code should be commented in the following way to work with doxygen.

The first file of each library defines a ``module'' via a special comment line:

/*! \defgroup PSIO libpsio: The PSI I/O Library */

Note the exclamation mark above -- it is required by doxygen. The line above defines the PSIO key and associates it with the title ``The PSI I/O Library.'' Each file belonging to this group will have a special comment of the following form:

/*!
** \file close.c
** \ingroup (PSIO)
*/

This tells doxygen that file close.c should be documented, it should be added to the list of documented files, and it belongs to the PSIO group.

All functions should be commented as in the following:

/*!
** PSIO_CLOSE(): Closes a multivolume PSI direct access file.
**
**  \param unit = The PSI unit number used to identify the file to all read
**                and write functions.
**  \param keep = Boolean to indicate if the file should be deleted (0) or
**                retained (1).
**
** Returns: always returns 0
**
** \ingroup (PSIO)
*/

int psio_close(ULI unit, int keep)
...

This will add the function psio_close to the list, associate it with the PSIO module, and define the various arguments.