Documenting functions

Alexandre Julliard julliard at winehq.com
Thu Aug 2 12:54:30 CDT 2001


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.

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.

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 ;-)

-- 
Alexandre Julliard
julliard at winehq.com




More information about the wine-devel mailing list