Re: [boost] Coding guidelines - function interface documentation

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-07-10 21:27:43

At 05:37 PM 7/10/2001, David Abrahams wrote:

 >> * 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.
 >
 >I don't think I agree here. Even internal functions which are not part of
 >the public interface are part of the private interface. I don't think an
 >inline implementation documents anything except an implementation. Every
 >function deserves documentation, and code is almost never a substitute. A
 >comment allows you to test a function, or to change its implementation, 
and
 >to know what you're aiming for.

Well, it's up to you.  I will give one example, however, of code written by 
you:

   template <class T>
   T next(T x) { return ++x; }

Does this really need anything more?

 >> * Effects: the actions performed by the function, especially
 >side-effects.
 >> Postconditions: the observable results established by the function.
 >
 >The issue of side-effects gets very interesting. I've recently been
 >emailing
 >with Scott Meyers who is having a hard time putting the effects of
 >functions
 >(say, those giving the strong exception-safety guarantee) in simple and
 >precise terms. I don't blame him. The difficulty occurs when a function
 >calls back into client code (e.g. when the client supplies a template
 >parameter, a derived class instance overriding a virtual function, or a
 >function pointer). To be really precise about this, you have to specify 
the
 >assumptions that the library makes about which client operations undo 
which
 >other ones (e.g. construction <=> destruction).

Yes, agreed.  But I'm not sure the guidelines are the right place for going 
into details of "how to describe various common and uncommon side effects". 

 >> * Throws: identifies any exceptions thrown by the function, and the
 >> conditions that would cause the exception.
 >
 >Here again it gets kind of interesting, since client code called by the
 >library can throw exceptions. Since most of our code is probably
 >exception-neutral, we will want a blanket statement somewhere that client
 >code is allowed (unless otherwise specified) to throw anything and that 
we
 >will pass the exception to the library's caller.

Yes.  The above wording was cut right out of the standard, which of course 
has that sort of blanket statement in the library introduction.  Also a 
statement to the effect that any library function can throw bad_alloc.

 >
 >> Also gives notice if the
 >> function provides anything other than the strong exception-safety
 >> guarantee.
 >
 >I could have sworn I changed that! I strongly believe the default 
guarantee
 >should be the basic guarantee.

Maybe I was working with an older version.  I thought it was current, 
though.

 >> * Complexity: the time and/or space complexity of the function.
 >
 >I think there are domains in which this may be irrelevant, or left as 
QOI.
 >For example, we don't document the complexity of the iostreams operations 

 >in
 >the standard. It might be too burdensome to ask the author of... oh, just
 >for instance, the Python library (!) to document the complexity of
 >functions which are expected to have a huge constant factor anyway.

Again, I just copied the standard.  For Boost, and many libraries, 
complexity should only be specified when the effort of doing so (with its 
implied constraint on implementors) is sufficiently offset by the benefits.

Thanks for continuing to work on the guidelines.  I think they are a 
valuable contribution, and deserve wider publication.

--Beman