Re: [OT?] Coding Style

[Larry McVoy]

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 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.