Source Internal Documentation - Best Practices

Introduction

Each source file must contain certain documentation within the file. Each source file must contain a copyright notice and heading. Every external interface, any structure/class or function which may be used outside the program unit in which it is defined, requires documentation defining its purpose and input-output performance. Scripts, including shell and Perl scripts, must have usage documentation.

Third party source is not required to have documentation added unless it is modified for use at ITTC. For modified third party source an appropriate ITTC copyright notice is added. Modifications must be documented at the place of the modification.

Heading

The heading is at the top of a file and contains a copyright notice followed by a synopsis, possibly a usage statement and authoring information. The usage statement is only required for scripts, program 'main' files and 'make' files.

Copyright Notice

All ITTC originated source files must contain a copyright notice as the first content of the file. There are 4 forms of copyright notice:

The fully restricted source copyright only allows the source to be used within ITTC. This is the default copyright to use unless the project director explicitly specifies use of one of the other copyright notices.

The open source copyright is added to open source that we obtain from a third party and modify for our own purposes and make available publicly. The original copyright notice must remain with the source also.

The education only source copyright is added to software made publicly available with the restriction that it can not be used commercially.

The GNU source copyright is the standard GNU copyright notice.

Synopsis

The synopsis states the purpose of the file. The synopsis should normally be one or two sentences. If the synopsis can't be stated in two sentences then contents of the file may be too disparate and could be separated into two or more files.

Example:

Synopsys: Function to control the Pan and Tilt of the VCC3 PTZ camera.

Usage Description

The usage section is only needed for those files that are given arguments from a command line. These would be files for scripts, 'make' files and files containing a program's 'main' function. The usage must contain at least one line showing the optional an required arguments. It is recommended that there be a one line description for each argument, particularly for single letter optional arguments.

A useful notation shows optional arguments in square brackets ([]), required arguments in angle brackets (<>) and repeating arguments followed by an ellipsis (...).

An example is:

Usage: scatter [-v] [-q] <filename>...

The name of the program is 'scatter'. Both '-v' and '-q' are optional arguments. The 'filename' is a required argument but there can be more than one filename argument.

Program Main File and Script File

In the file containing a script or the 'main' entry point for a program the 'Usage' documentation line in the heading can be omitted if there is a 'Usage' subroutine appearing as the first function in the file. The 'Usage' routine is used by the program or script to print 'Usage' information to standard output. It is called when the user gives an invalid argument on the command line or a command line argument requesting the 'Usage' information.

Makefile

A 'make' file must contain 'Usage' information in the heading about any macros or non standard targets that can be supplied to the 'make' utility for the makefile. Standard targets can be found in the ??? document.

Author

The name of the original author of the file and the date of the creation of the file must appear in the heading of source files. When significant changes are made to the file it is recommended that the author section be appended with the name of the person modifying the file and the date plus a one sentence description of the change.

For minor changes to a file the author section should not be changed. The changes made and the person that made them can be determined using the source revision control utility.

Object Declaration Section

An Object Declaration Section refers to the code that declares structure fields and class fields/members in languages like 'C' and 'C++'. For shared structures and classes this type of code is in an 'included' file.

The outline of a documentation object declarations is:

Object Heading

A heading comment for an object is optional but recommended for class objects to explain the purpose of the class. This can be important for a class that is intended to be inherited by other classes. A one or two sentence description is usually sufficient. If the object is an implementation of an API then the specification identifier of the specification that the object implements must be included in the header.

Documentation of class member functions occurs in the headers of the definition of the functions.

End of Line Comments

End Of Line (EOL) comments are encouraged for structure and class fields where the intent is not obvious from the field name. An EOL comment is a comment on the same line as the field declaration following the declaration. Since it is on the same line as the code it documents it will generally be moved or deleted along with it's code. This reduces the likelihood that it will eventually become wrong documentation.

Function Section

Function source is most commonly source code for a function in a language like 'C' or member functions in languages like 'C++'. It can also include functions in shell scripts.

The outline of documentation for functions is:

 

Heading

For each function in a file, function heading documentation must precede the function. The heading must contain at least one sentence of synopsis outlining the purpose of the function. If the function creator is different than the file creator then the name of the function creator and the date must be included.

For each function a brief description of each argument's non obvious limitations is required. If it is obvious from a quick glance of the code what the restrictions on an argument are then documentation of the argument is not required. A rule of thumb is that a 5 line function is easy enough to understand without documentation. Since the usage of arguments is one of the most commonly changed aspects of a function the documentation of arguments has the highest chances of being incorrect as the lifetime of a file increases. Argument documentation must be carefully considered for each function when the function is first written.

Return values of a function must be given a little more consideration than arguments. It is generally more difficult to determine what the possible return values for a function can be when there are multiple return locations

in a function. Multiple return locations are not a good programming practice but there are rare occasions where it is required.

If a function is part of an API or a program 'main' there must be an external Specification Document that gives a full description of the program's command line syntax or for an API function its arguments and its return values. For the heading it is not required to repeat the contents of the specification. The function heading must contain the specification identifier the API function implements or the program's 'main' implements.

Refer to external documentation where applicable. If a program unit implements a well known algorithm that is documented elsewhere (e.g. a textbook or some other implementation), include references here. These references which outline the algorithm being implemented are much more concise (and accurate?) than attempting to incorporate the algorithm description in text lines.

Inline Documentation

Inline documentation consists of comments between lines of code. It is not necessary to document a line or section of code where the intent of the code is obvious. Obvious intent of the code relies heavily on well chosen variable and function identifiers.

In sections of code where it is not obvious what the intent is, even with well chosen identifiers, one or two sentences of comment are recommended preceding the code.

If you can accurately and completely define what a function does in the documentation of its interface, as described in the preceding sections, then there is often little need for documentation of how it is implemented within the code itself.

If the code is "self-documenting" (uses descriptive variable names, uses only well-formed control structures with limited nesting, etc.) then inline code documentation may already be complete. If the code is not "self-documenting", then perhaps improving the readability of the code itself will be more effective than adding textual comments to explain an obtuse section of code.

Insert inline documentation to clarify important details that are not covered by other guidelines suggested here. Here are simply a few suggestions to provide specific examples:

As mentioned several times in this document, consider what a person might need to know in order to understand this Program unit if he/she was asked to correct a bug one year later.

Avoid repetitive information. This wastes your time and space. For example, a comment to identify the input argument, ANGLE, as "the input angle" adds no new information. Stating that ANGLE should be expressed in radians, however, does provide important information.

Embedding a revision history in the text of the code is discouraged. Careful documentation of revision history is critical for the long term development and maintenance of code. We suggest the careful use of revision control system for recording and maintaining this information. These systems automatically capture the time and author of every change, and a description of the changes (as entered by the person checking in the code). Furthermore, this historical information is not generally pertinent to the understanding and use of the code.

End of Line Documentation

See 'End of Line Documentation' subsection of the 'Object Declaration' section.

Examples:

Script

Example for a 'sh' script.

------------
#!/bin/sh
# Copyright (c) 2000 The Information and Telecommunication Technology Center
# (ITTC) at the University of Kansas
# ALL RIGHTS RESERVED
# FooBar looks for all 'Foo' files in the current directory and performs
# the 'Bar' operation on them with output to standard out.
#
# Author: Leon S. Searl, 20000413
# Usage: FooBar [-q]
-----------

Functional Source

Example for a 'C' language source file.

------------

/* Copyright (c) 2000 The Information and Telecommunication Technology Center
* (ITTC) at the University of Kansas
*
* This software is provided 'as-is', without any express or implied warranty.
* In no event will the authors or owners be liable for any claim, loss or
* damages, including attorneys' fees, arising from the use of this software.
*
* This software is made available for educational, noncommercial use only.
* It may be copied, duplicated, or modified for such educational, noncommercial
* use, provided such copies, duplicates, or modifications include proper
* copyright notices regarding this software.
*
* Send comments or questions about this software to:
*
* Joseph B. Evans, evans@ittc.ukans.edu or
*
* Synopsis: The FooBar entry function parses the string argument to
* determine if it contains a syntax error.
*
* Author: Leon S. Searl, 20000413
*/

#include "FooBar.h"

/* Function: FooBar - see above description.
* returns - returns pointer to position in string
* where error occurs, otherwise returns NULL on no
* error.
*/

char *
FooBar ( const char * str ) {
...
}

------------