Re: "Tricks" of the "Trade"
Re: "Tricks" of the "Trade"
- Subject: Re: "Tricks" of the "Trade"
- From: Rob Rix <email@hidden>
- Date: Fri, 8 Jun 2001 01:20:14 -0400
I think of comments less as two separate stories and more as a story with
footnotes. Comments should not merely translate the code into Natural
Language; those comments get out of date very quickly. Comments should
be used to explain design decisions, describe pre- and post- conditions,
explain usage, and document thought processes that went into a section of
code. Oh, also use comments to detangle ugly code -- but this is
secondary, in my opinion.
Personally, I use comments to describe formats in interface files (so, if
I'm returning a Dictionary, I might use the comment to list the key names
that will be present), and to quickly explain blocks of code (for instance,
something like "this for loop goes through the items in the array and..."
or whatever) so you can get an idea of what it does without having to read
every line.
Also, self-documenting code is a great idea, but unfortunately, the
language is sort of English-esque, and so there is often another, and
unintended, way of taking something.
-- Rob
Murphy strikes again!