Alexandre Julliard julliard@winehq.com wrote in article 87zo9iwdnt.fsf@mail.wine.dyndns.org...
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.
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