On Monday 12 January 2009 12:21:09 Daniel Pittman wrote: 8x< > As a rule of thumb comments serve two purposes in code: they document > the high level design of the code, and they document the intimate detail > of implementation. > > For high level design a single block, at the start or end of the module, > is generally best. Something like the manual page structure is > generally useful; it covers what a reference manual would reasonably > include. > > This is also where you should include, for example, notes on the overall > performance of the module, why you selected the high level algorithms, > and so forth.[1] > > > It sounds like you are mostly talking about the intimate details of > implementation, though, rather than the high level stuff. > > At that level you want to explain the *why* of the code: not the high > level stuff (this is a shell sort), but the low level stuff (this > mangling of the name is to handle quoting for the next three lines...) > > > Your audience here is someone from the future: in six months, when the > script needs to change, someone has to come back and make changes. />x8
Well said. (As also your other notes.) I would just add: Use function header documentation! Find a template that suits you and stick to it like glue. Too many times I have caught myself out six months later trying to figure out what the heck the rationale, result and parameters for "this" function are. I mean, I must have put this code into a function for some reason, usually re-useabilty, and usually when I think "I think I've got a routine for that somewhere", I usually also think " I hope-to-dog that I documented it". And finally, dont forget the power of //hack and //todo! hth bruce -- SLUG - Sydney Linux User's Group Mailing List - http://slug.org.au/ Subscription info and FAQs: http://slug.org.au/faq/mailinglists.html
