Jeremy White jwhite@codeweavers.com writes:
I would say that I would rather have 100% of the effort aparticular 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 havebeen 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 ;-)