Coding guidelines - function interface documentation

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-07-10 15:31:05

Sections 7.3 and 7.4 say:

7.3.   All function interfaces must be commented (except for copy 
constructors, operator overloads such as copy-assignment and dereference, 
and destructors). The comment describes precisely what the function 
requires, what its effects are (especially including side-effects), and 
gives notice if the function provides anything other than the strong 
exception-safety guarantee. Accuracy is more important than brevity*.

7.4.   Comment function interfaces in just one place. It can be difficult 
enough just to keep comments synchronized with code. Just as not 
duplicating code reduces the risk that some code will grow stale, 
commenting a function in one place only reduces the risk of comments not 
being maintained together. Whether a function interface comment must appear 
at the point of declaration or of definition is covered below.

I have several concerns with the above:

* They fail to mention the case of functions which are documented 
externally, and thus should not be documented via comments in the code.

* A function documentation form which more closely follows the C++ standard 
should be encouraged, IMO.  The standard form is familiar and will ease the 
transition from Boost documentation to formal standard, should the function 
become part of the standard.

* Particularly for small, simple functions which are part of the 
implementation (and thus not part of the published interface), inline 
implementation is often the simplest and clearest way to document a 
function.

Here is a reformulation:

7.3 All function interfaces must be documented, except for functions with 
obvious semantics, such copy constructors, operator overloads such as 
copy-assignment and dereference, and destructors. Even these functions must 
be documented if their semantics are in any way unusual.

7.4 Document function interfaces in just one place. It can be difficult 
enough just to keep documentation synchronized with code. Just as not 
duplicating code reduces the risk that some code will grow stale, 
documenting a function in one place only reduces the risk of the 
documentation being maintained inconsistently.

7.4+ Document functions in an appropriate format:

* Functions which are part of a library's public interface should be 
documented in the project's preferred external document format. (For Boost, 
that's HTML.) For functions documented externally, the code should include 
a comment (possibly given once a the beginning of the header file) pointing 
to the appropriate documentation. As more and more program editors 
recognize URL's in comments, it makes sense for the pointer to be a valid 
URL.

* Functions interfaces not documented externally (presumably because they 
are implementation helpers not part of the published interface) are 
documented by program comment, which must appear at the point of 
declaration or of definition as described below.

*Inline implementation of implementation helper functions may serve as 
documentation, provided the implementation is very short, simple, and has 
the net effect of making program meaning easier to understand.

7.4++ Document functions in standard form.  The elements of standard form 
function documentation (ISO 17.3.1.3) are given below. (Rationale is an 
addition to the standard form.) Elements which do not apply should be 
omitted. Accuracy is more important than brevity*.

Signature(s) of the function(s) to be documented, follow by:

* Requires: the preconditions for calling the function, such as valid 
values for arguments.

* Effects: the actions performed by the function, especially side-effects.
Postconditions: the observable results established by the function.

* Returns: a description of the value(s) returned by the function.

* Throws: identifies any exceptions thrown by the function, and the 
conditions that would cause the exception.  Also gives notice if the 
function provides anything other than the strong exception-safety 
guarantee.

* Complexity: the time and/or space complexity of the function.

* Rationale: a description of why the function is or isn't designed in a 
certain way. For example, why an argument or return value of a type 
normally passed by reference is passed by value (or visa versa).

Comments?

--Beman