[Exceptional C++ Style] Exceptional C++ Style - Item 24: ConstantOptimization

[James Dennett]

On Tuesday, January 25, 2005, at 01:54 AM, Paul Grenyer wrote:

> Hi
>
>> Although I would prefer to see "proper" documentation of
>> what a function is supposed to do, than have to deduce it from
>> the signature.
>
> I wouldn't! Documentation in this context is an extra unnecessary 
> overhead
> and isn't necessarily updated when the function is.
>

I suspect you're talking at cross purposes.  Documentation of what the
function does is valuable.  Documentation of whether it modifies an
argument can be considered optional, in the normal (99.9%) case where
you can tell that from looking at the parameter type.

> A function is a method of encapsulation like any other. I don't care 
> what
> happens inside as long as I get the desired result.

Which you know from the documentation, only.

> However, I do care if it
> is going to modify the parameters that I pass to it and I can deduce 
> that
> from how they are passed.

Usually; callbacks, for example, may not use all freedoms they are
granted.

> If the function name and parameter names are clear
> and well chosen it should also be possible deduce what the 
> modification will
> be.
>
In all boundary cases?  I tend to find that I need documentation for 
that,
quite often.

-- James