Re: [boost] Coding guidelines - function interface documentation

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-07-10 22:23:35

----- Original Message -----
From: "Beman Dawes" <bdawes_at_[hidden]>

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?

Not in the code, but in the html, certainly.
However I admit I'd be tempted to leave that undocumented if it were an
implementation detail.

>  >> * 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".

If you tell people they should document the effects, you ought to say what
you mean.

>  >> 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.

No, somehow my changes got lost.

>  >> * 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
>
> 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.

Great. Would you like to submit updated proposed changes?

-Dave