RE: [OT?] Coding Style

[Jonathan Earle]

> -----Original Message-----
> From: Larry McVoy [mailto:[e-mail]]
> 
> On Mon, Jan 22, 2001 at 11:04:50AM -0500, Jonathan Earle wrote:
> > > -----Original Message-----
> > > From: profmakx.fmp [mailto:[e-mail]]
> > > 
> > > So, every good programmer
> > > should know where to put comments. And it is unnecessary to 
> > > put comments to
> > > explain what code does. One should see this as stated in the 
> > > CodingStyle doc.
> > > Ok, there are points where a comment is good, but for example 
> > > at university
> > > we are to comment on every single line of code ...
> > 
> > WRONG!!!
> > 
> > Not documenting your code is not a sign of good coding, but 
> rather shows
> > arrogance, laziness and contempt for "those who would dare 
> tamper with your
> > code after you've written it".  Document and comment your 
> code thoroughly.
> > Do it as you go along.  I was also taught to comment nearly 
> every line - as
> > part of the coding style used by a large, international 
> company I worked for
> > several years ago.  It brings the logic of the programmer 
> into focus and
> > makes code maintenance a whole lot easier.  It also helps 
> one to remember
> > the logic of your own code when you revisit it a year or more hence.
> 
> Please don't listen to this.  The only place you really want 
> comments is
> 
>     a) at the top of files, describing the point of the file;
>     b) at the top of functions, if the purpose of the 
> function is not obvious;
>     c) in line, when the code is not obvious.
> 
> If you are writing code that requires a comment for every 
> line, you are 
> writing bad, obscure, unobvious code and no amount of 
> commenting will fix
> it.

The point of comments is not to "fix" bad code, it's to provide
understanding.  As the original poster said, _you_ may understand your code,
but that in no way implies that _I_ will, or your co-worker down the hall
will, etc.  I'm not suggesting that a statement like "counter=0;" at the
start of a function be commented, but other operations should be.  "Why do
we want this file written in /proc - wouldn't syslog have worked better?"
"Why is this loop skipping the first seven elements?"  "Why is this
structure used here instead of a simple array?"  "What on earth does
m->n->o->num represent?"

> The real reason to sparing in your comments is that code and 
> comments are
> not semantically bound to each other: the program doesn't 
> stop working when
> the comment becomes incorrect.  It's incredibly frustrating 
> to read a comment,
> believe you understand what is going on, only to find out 
> that the comment
> and the code no longer match.   

Comments should be updated when code is updated.  I believe that
documentation is of far greater value than code itself.  Code can be
changed, however, logic drives the code.  Without a good understanding of
the latter, the former is of little value, IMHO.

Cheers!
Jon