Re: [OT?] Coding Style

[Steve Underwood <steveu@coppice.org>]

Larry McVoy wrote:
> 
> On Mon, Jan 22, 2001 at 11:04:50AM -0500, Jonathan Earle wrote:
> > > -----Original Message-----
> > > From: profmakx.fmp [mailto:profmakx.fmp@gmx.de]
> > >
> > > 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.
> --
> ---
> Larry McVoy              lm at bitmover.com           http://www.bitmover.com/lm

It seems the great majority of heavily commented programs I have seen
never commented anything useful. The ooooh so useful the little
snippets, like:

    /* Beware: The next two lines might seem weird, but they work around 
       a bug in some revisions of XYZZY. */

were seldom there, but:

    a = b + c; /* add a to b, and store it as c */

were there in bundles. During a period of making a liveing out of
sorting out severly screwed up projects I made a little comment
stripper. I found comments so unreliable, and so seldom useful, I was
better off reading the code without the confusion they might cause. I
do, however, try to document the non-obvious through comments in what I
write.

Some people still seem to be living in the age of K&R C, with 6 or 7
character variable names that demand some explanation. Maybe some day
they will awake to the expressive power of long (and well chosen) names.

Regards,
Steve
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/