Gervase Markham wrote:
> Are we looking for something like:
>
> Every function should have a Javadoc/Doxygen comment at the head
> describing what it does, its inputs and outputs, and possibly what it
> _should_ do (the sort of comments normally buried in the source saying
> "XXX FIXME we need to handle condition Y".)
This seems like overkill. Some areas of the code are full of
complicated functions that do need this type of documentation (e.g.,
[1]), while others are full of small, self-documenting functions where
such documentation is overkill and only clutters up the code and makes
it harder to read and harder to find the important points in the
documentation within the obvious comments (e.g., [2]).
-David
[1]http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/layout/html/base/src/nsLineLayout.cpp&rev=3.99&root=/cvsroot#1966
[2]http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/htmlparser/src/nsIParser.h&rev=3.105&root=/cvsroot#156
--
L. David Baron <URL: http://www.people.fas.harvard.edu/~dbaron/ >
[EMAIL PROTECTED] [EMAIL PROTECTED]
