Olin Lathrop wrote:

> This is exactly why "self documenting" code is so dangerous.  By itself it
> is a good idea, but it leads people to believe they don't have to write any
> separate documentation.  

IME it only leads people to that conclusion who wouldn't write good
comments anyway -- because they don't understand what should go in a
comment. 

> I would like to see something like:
> 
>   for (int i = 0; i < nPoints; ++i) { //once for each polygon vertex

Rather than this comment, I'd suggest

for( int iVertex=0; iVertex<iPolygonVertexes; ++iVertex ) {
  // ...
}

... plus a comment that explains /why/ you are doing this (not what you are
doing; this should be obvious from the code itself).

One additional advantage is that inside the loop, the iVertex is more
expressive than the i. (On a side note: single letter variable names can be
a real pain to hover over, which is what you can do with some debuggers to
see the value. If you like "i", maybe try "ii" -- a bit easier to hit with
the mouse :)

> Comments are not just to explain code, but also to help you make sure your
> code does what you intend it to do.  

Exactly. So just repeating what the code is doing doesn't really do it --
it needs to come from a different angle (that's the "why" aspect that was
already mentioned).

Gerhard

-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist