| |||||||||||||
Quotes of the week - all about documentationQuotes of the week - all about documentationPosted Dec 12, 2008 17:51 UTC (Fri) by hppnq (guest, #14462)In reply to: Quotes of the week - all about documentation by iabervon Parent article: Quotes of the week - all about documentation Some projects of course have very strict guidelines as to what is accepted in code and comments. I don't think that these are counterproductive, in general. From what I remember about the Apache code -- we're talking 1999 here ;-) -- every routine was nicely documented at the top but the code did not have too many comments interspersed. It worked like a charm, I think, and many projects utilize a similar strategy. I think the documentation effort should be geared more towards such a situation than one in which each bit of code is properly documented: that is, indeed, quite a waste of time and energy. It can never be wrong to document what a well-defined part of a bigger picture does (so this should be the rule), whereas documenting bits and pieces has to be indicative of problems in the code (so this should be the exception). I would therefore say that maintainers have a special interest and responsibility when it comes to documentation.
(Log in to post comments)
|
|||||||||||||