Boost logo

Boost :

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk