Difference between revisions of "Standards for Internal Documentation"

Revision as of 02:34, 29 August 2014

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 DREAM we will use it to provide external documentation on the 4Cs: compo- nent functionality (i.e. computation), configuration, communication (through ports), and coordination (through ports, including the module-name port). The Doxygen documentation system [5] is used to extract the documentation comments and cre- ate 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 com- ment, 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 documen- tation 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 config- uration 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 com- ment. 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 docu- mented. The following is a list of the mandatory sections for which documentation comments must be pro- vided. These are taken from the example protoComponent.h file and you should refer to the full listing of this file in the DREAM SVN repository (see Part II, Section 6 and Appendix A, Section A.3) and to the software development guidelines on the DREAM wiki (see Part III, Section 5). /**

* @file protoComponent.h

...

* \section lib_sec Libraries

...

* \section parameters_sec Parameters
*
* Command-line Parameters 

...

* Configuration File Parameters 

...

* \section portsa_sec Ports Accessed

...

* \section portsc_sec Ports Created
*
* Input ports

  - \c /protoComponent \n
...
* Output ports
*
   - \c /protoComponent \n

...

* Port types 

...

* \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
• protoComponent --name <componentName>
• *

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

* \author
* <forename> <surname>
*
* Copyright (C) 2014 DREAM Consortium

• */

B.3 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. /*

* Copyright (C) 2014 DREAM Consortium
* FP7 Project 611391 co-funded by the European Commission
*
* Author:  <name of author>, <author institute>
* Email:   <preferred email address>
* Website: www.dream20202.eu
*
* 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, and *.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 //}