Standards for Internal Documentation

General Guidelines

Two types of comments are required: documentation comments and implementation comments. Implementation comments are those which explain or clarify some aspect of the code. Documentation comments are intended to be extracted automatically by the Doxygen tool to create either HTML or LaTeX documentation for the program. Documentation comments describe the functionality of a component from an implementation-free perspective. They are intended to be read by developers who won’t necessarily have the source code at hand. Thus, documentation comments help a developer understand how to use the component through its application programming interface (API), rather than understand its implementation.

Documentation comments are delimited by /** ... */.

Implementation comments are delimited by /* ... */ and //.

Implementation comments should be used to give overviews of code and provide additional information that is not readily available in the code itself. Comments should contain only information that is relevant to reading and understanding the program.

Information about how the executable should be compiled and linked or in what directory it resides should not be included as a comment. This information should go in the README.txt file.

All comments should be written in English.

Documentation Comments

Documentation comments often describe classes, constructors, destructors, methods, members, and functions. However, in CINDY we will use it to provide external documentation on the 4Cs: component functionality (i.e. computation), configuration, communication (through ports), and coordination (through ports, including the module-name port).

The Doxygen documentation system is used to extract the documentation comments and create external documentation in HTML or LaTeX. Although Doxygen supports several documentation formats, we will stick to the Javadoc format as it is widely-accepted and it facilitates visually-pleasing and unobstrusive comments.

Each documentation comment is set inside the comment delimiters /** ... */. Within this comment, several keywords are used to flag specific types of information. We will treat each of these below by way of an example taken from the prototype component module, specifically the documentation comments in protoComponent.h. Since we are not using Doxygen documentation comments to described classes, there are no documentation comments in the in the three *.cpp files.

Note that to use the JavaDoc style JAVADOC_AUTOBRIEF must be set to YES in the Doxygen configuration file.

Note also that blank lines are treated as paragraph separators and the resulting documentation will automatically have a new paragraph whenever a blank line is encountered in a documentation comment.

The First Documentation Comment

All source files that contain general documentation comments (rather than class documentation comments) must begin with a documentation comment that identifies the file being documented, as follows.

/** @file <filename> <one line to identify the nature of the file>
 *
 * Version information 
 * 
 * Date 
 */

This applies in particular to the <componentName>.h file where the component API is documented.

The following is a list of the mandatory sections for which documentation comments must be provided. These are taken from the example protoComponent.h file and you should refer to the full listing of this file in the CINDY repository and to the software development guidelines on the wiki.

/**
*@file protoComponent.h
 *

...

 * \section lib_sec Libraries

...

 * \section parameters_sec Parameters
 *
 * <b>Command-line Parameters</b>

...

 * <b>Configuration File Parameters</b>

...

 * \section portsa_sec Ports Accessed

...

 * \section portsc_sec Ports Created
 *
 * <b>Input ports</b>
 
   - \c /protoComponent \n

 ...

 * <b>Output ports</b>
 *
    - \c /protoComponent \n

...

 * <b>Port types </b>

...

 * \section in_files_sec Input Data Files

...

 * \section out_data_sec Output Data Files

...

 * \section conf_file_sec Configuration Files
 *
 * \c protoComponent.ini

...

 * \section tested_os_sec Tested OS

...  

* \section example_sec Example Instantiation of the Module 
*
* <tt>protoComponent --name <componentName> 
*
*
...

--context components/<componentName>/config 
--from <componentName>.ini </tt>

* \author
* <forename> <surname>
*
* Copyright (C) 2015
*
*/

Implementation Comments

Programs can have four styles of implementation comments: block, single-line, trailing, and end-of- line.

Block Comments Block comments are used to provide descriptions of files, methods, data structures, and algorithms. Block comments may be used at the beginning of each file and before each method. They can also be used in other places, such as within methods. Block comments inside a function or method should be indented to the same level as the code they describe.

A block comment should be preceded by a blank line to set it apart from the rest of the code.

/*
 * Here is a block comment.
 */

The First Block Comment All source files should contain a block comment that gives the copyright notice, as follows.

/*
 * Author:  <name of author>, <author institute>
 * Email:   <preferred email address>
 * Website: <preferred web address, if any>
 *
 * This program comes with ABSOLUTELY NO WARRANTY 
 */

This text is not included in a documentation comment (see below) because we don’t want it to be extracted into the documentation by Doxygen. The comment should be placed at or close to the beginning of every source file: *.h, *.cpp<code>, and <code>*.c.

Single-Line Comments Short comments can appear on a single line indented to the level of the code that follows. If a comment can’t be written in a single line, it should follow the block comment format.

if (condition) {

   /* Handle the condition. */

... 
}

Trailing Comments Very short comments can appear on the same line as the code they describe, but should be shifted far enough to separate them from the statements. If more than one short comment appears in a segment of code, they should all be indented to the same level.

if (a == b) {
   return TRUE;
} 
else {
   return general_answer(a);

   /* special case */ 
   /* only works if a != b */

}



End-Of-Line Comments The // comment delimiter can comment out a complete line or only a partial line. It shouldn’t be used on consecutive multiple lines for text comments. However, it can be used in consecutive multiple lines for commenting out sections of code. Examples of all three styles follow.

if (foo > 1) {

   // look left

   ... 
}
else {
   return false;  // need to explain why
}
//if (foo > 1) { 
// 
//   // look left
// ...
//}
//else {
//   return false;  // need to explain why
//}