Regarding coding style

[Grant Edwards]

On 2008-03-08, castironpi at gmail.com <castironpi at gmail.com> wrote:

> Does one side of this hold that there are no -good- comments?

I wouldn't say there are _no_ good comments, but I would say
that 90+% of the comments I've seen in my lifetime were bad.
Most of them were bad to the extent that anybody new to the
code would be best served by deleting them before trying to
understand what was going on.

I do think that a comment at the beginning of a function/module
that describes its general purpose can be a good thing.  A
comment explaining a particularly opaque algorithm can be
useful as well.

<rant>
What I really can't stand are the pointy-haired comment blocks
at the beginnings of C/C++ functions that do things like tell
you the name and return type of the function and list the names
and types of the parameters. Gee, thanks.  I never could have
figured that out from looking at the source code itself. IMO,
comments explaining what the parameters are used for usually
indicates that the parameter names were poorly chosen.

I'm also a bit baffled by people who put a comment at the top
of every file that tells you what the filename is.  I sometimes
wonder how/where these files were created. All of the OSes I've
ever used had a feature called a "filesystem" which kept track
of info like the names of files.  It must be a bitch-and-a-half
to work on an computer that doesn't keep track of filenames and
makes the user do it.

When was the last time you thought to yourself: "Gee, I wonder
what's the the name of that file over there? I guess I'd better
open the file and look at the comment at the top to see what
the filename is?
</rant>

-- 
Grant Edwards                   grante             Yow!  .. does your DRESSING
                                  at               ROOM have enough ASPARAGUS?
                               visi.com