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
** \ingroup PSIO
** \brief A brief descriptor of the file should go here
**
** A more detailed description of the file can go here
*/

This tells doxygen that this file should be documented, it should be added to the list of documented files, and it belongs to the PSIO group. Do not put the actual filename after the file directive, because current versions of doxygen have trouble when duplicate filenames appear in different modules. Leaving the filename blank after the file directive lets doxygen create a unique filename using part of the file path.

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.

Please note: In addition to listing all the parameters and return values, it is very valuable to explain what the function actually does. Add this explanation immediately after the function name (see above). This explanation might be a few words, or an entire paragraph, as necessary.

It is possible to include formulas in the doxygen documentation and to have them properly formatted when output to HTML or LaTeX. If the formula appears in the running text of a doxygen comment, enclose it within a pair of $\backslash$f$ commands, and format it according to LaTeX rules. To make the formula centered on a new line, enclose it within $\backslash$f[ and $\backslash$f]. If the formula is to be in an environment other than simple math mode (e.g., an eqnarray, then begin the environment with $\backslash$f{environment} and end it with $\backslash$f}, where environment is something like eqnarray*. According to the doxygen documentation, the program can have trouble recovering from typos in formlas, and to get rid of a typo in a formula it may be necessary to remove the file formula.repository from the HTML directory.