Documenting functions

[Bill Medland]

Alexandre Julliard <julliard at winehq.com> wrote in article
<87zo9iwdnt.fsf at mail.wine.dyndns.org>...
> Jeremy White <jwhite at codeweavers.com> writes:
> 
> >      I would say that I would rather have 100% of the effort a
> > particular developer *wants* to put in, rather than only
> > have his/her coding efforts.
> 
> Absolutely; I'm not going to discourage anybody from writing doc if
> they feel like it. But I don't want anyone to feel somehow obliged to
> spend time on the doc if they'd rather be writing code, which I expect
> is the case with most developers...
> 
> > However, I think that there should be a standard function
> > header, with a standard place to put notes and comments
> > in general about a function.
> 
> I don't see a need to standardize anything. If you want to add a
> comment before a function just do it, there is no need for a standard
> format, plain text works just as well.
> 
> >      I have been trained, and I suspect that many of us have
> > been trained, to look at a function header for general
> > tips and tricks before diving into the code.  I know
> > this is sacriledge to you, Alexandre, but there are some
> > of us who like to quickly look at a function, rather than
> > always reading the code to understand it completely.
> 
> I think you misunderstand my position; I'm not opposed to having a
> comment at the start of the function explaining the general goal and
> the non-obvious things going on. But if you need more than a couple of
> paragraphs to do this, then either there are too many non-obvious
> things going on in your function, or you are wasting space explaining
> the obvious.

Ay, there's the rub.  It isn't our function.  It';s Microsoft's function. 
Now was it Holub or McConnell that complains about functions having weird
behaviour on certain inputs.
The biggest problem, I believe, is the functions that take flags.  Bear in
mind that a single DWORD argument used for flags is equivalent to up to 32
boolean arguments.  Documenting the relationship between those is a pain
but it needs to be done if we expect compatibility.
The next worst is handles or pointers to complex structures.  What aspects
of the object are relevant?
And on the subject of non-obvious..The usual claim is
1. A comment should not state the obvious
2. If the converse of a statement in a comment is obvious then don't bother
with it.
In my experience these are both true but with provisos.
1  What is obvious to you today is probably not going to be obvious to you
in 6 months
2. What is obvious to you is possibly not obvious to everyone else
3. The converse of a statement may be obvious to you.  It may also be
obvious to someone else.  The question is "is it the same for both people"

> 
> I do strongly think that the goal should be to write code that doesn't
> require documentation in order to be understood. Of course adding a
> small amount of comments is a good idea; but when you start having
> more lines of documentation than lines of code, something is very
> wrong IMO.

And this is where I started getting overjoyed by the capabilities of SGML
and the like.  I agree wholeheartedly that too much documentation is a bad
thing.  Which is why I think there is a need for documentation outside the
code, epecially in a networked shape (e.g. html/sgml) that can be
referenced.

> 
> But this is mainly a matter of personal taste, and except in extreme
> cases I'm not going to reject code because it has too much (or not
> enough) documentation. It may happen that some of your beloved
> horizontal lines get lost during the cvs commit though ;-)
> 

Bill