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

[James Dennett]

On Tuesday, January 25, 2005, at 07:46 AM, Paul Grenyer wrote:

> Hi
>
>> 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.
>
> Maybe. The problem is maintaining the documentation acurately.

If there's a difference between the documentation and the functionality,
probably both are wrong (as the cliche goes).

>
>>> 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.
>
> I disagree. If the function has a well chosen name and is considered 
> in the
> context of it's class/namesapce/etc they is _should_ be clear what it 
> does.
> Obviously I am describing an ideal world.

I'm afraid I'd call it an oversimplified world more than an ideal one.
Abstraction and economy of expression require us to define things
that are *not* obvious to get the "best" code.

>
>>> 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?
>
> Probably not. It's another ideal world thing.
>
My experience is that a good fraction of functions need more documented
than can be known from the name alone -- what does the function do in 
cases
of errors, for example, or what constitutes an error, or what 
environmental
factors might affects the functionality.

-- James