[lwip-users] RE: [lwip] Suggestion: javadoc

[Paul Sheer]

------=_Part_1215_3901369.1029845232532
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

> I mean extracting comments from the source code? 
> 

Source code that needs to much documentation is
bad source code. Linus said it in
/usr/src/linux/Documentation/CodingStyle :

"Comments are good, but there is also a danger of over-commenting.  NEVER
try to explain HOW your code works in a comment: it's much better to
write the code so that the _working_ is obvious, and it's a waste of
time to explain badly written code."

"Generally, you want your comments to tell WHAT your code does, not HOW. 
Also, try to avoid putting comments inside a function body: if the
function is so complex that you need to separately comment parts of it,
you should probably go back to chapter 4 for a while.  You can make
small comments to note or warn about something particularly clever (or
ugly), but try to avoid excess.  Instead, put the comments at the head
of the function, telling people what it does, and possibly WHY it does
it."

> > This is probably going to make people reel, but...
> 
> If I got you right your script is converting plain ascii files to html? 
> Are we not missing the connection to the source code then? 

yep, yep.

I have yet to see such a documentation system work
properly. TeX is the best example of doc+code together
and even this is yukky. (And Donald Knuth is a genious.)

-paul



Powered by World Online - http://www.worldonline.co.za



------=_Part_1215_3901369.1029845232532--

[This message was sent through the lwip discussion list.]