How is a programmer's time best spent?

[JSuros]

MarkN,


Let's keep this civil, shall we? I went back and read the article again and
to my mind it seems pretty clear that Dr. Kabutz is advising against comments
in general. He gives specific examples of bad (useless) comments and cites
anecdotes from his educational and professional experience to back up his
opinion.

I agreed with his assessment of the samples he cited, but disagreed on his
conclusions. I have seen comments used well to explain a tricky bit of code
and left entirely off whole functions where a "title block" explaining the
function's intended use was enough to serve for years of code reuse.

In OOP, quite a lot of code consists of objects from libraries calling other
objects from libraries. The names of these objects can become quite complicated,
especially when a property may be assigned a value returned from a method
of an object, each parameter of which may be the result of a previous method
call. Dr. Kabutz cites "java.awt.color.ColorSpace.getName()", for example.
The code for this method in its library is very simple, but that is only
half the story. In use, how readable would code be in a program that needed
to support calls to "java.swing.color.ColorSpace.getName()" in the same class?

My point is not that you couldn't reason out the meaning of such code, but
that it would take time. Time that a quick glance at comments might allow
you to avoid.

I wish Dr. Kabutz had specified what he might consider usefull comments,
rather than just fanning the fires of an issue which is almost as contentious
as the age old question of indenting code.


JSuros

[MarkN]

I was being civil. (I thought worse and didn't say it) Why didn't you ask
Jim-C to be civil? Sorry, but this format makes it really tough to see how
something is really being said. Anything below is said with civility yet
truthfully.

All I can say is you ARE (and most others) wrong in your understanding of
this article. And that was my point with my little comment. Many of the
the things we do in software development are result of having individuals
involved in software development who really don't have the skills to do it.
Critical thinking is very important to software development.

It was a very short article and he could have used better examples, but it
seems he used ones everyone could go look at.

No where in the article does he say or mean never comment. No where does
he say or mean comment just barely. He does say make better use of them.
And THAT is his point. We are told to comment all of our code so most coders
put comments that tell how and not what. Most of the time it was\is a waste
of the coder's and debugger's\recoder's time.

I don't think we really disagree that much. If it looks like code requires
a lot of comments then it should be comment and marked for refactoring.
Just make sure the comments really are useful.

Mark

[Paul Clapham]

<snip>
> I have seen comments used well to explain a tricky bit of code
> and left entirely off whole functions where a "title block" explaining the
> function's intended use was enough to serve for years of code reuse.
</snip>

This is exactly how it should be done. And as MarkN said, there are a lot
of people in this field with substandard skills (Sturgeon's Law: 90% of
everything is crap). Given this, tricky bits of code should be kept to a
minimum.

But I don't believe the main point of the article was whether comments
should or should not be used. At the end of the day, the meaning of the
program is the code. The comments may or may not be correct, but the
program works the same regardless. So, if you are good at reading and
understanding code, as I believe Kabutz is, why bother reading the comments?
At best they reiterate what the code does and at worst they are wrong.
Remember his title? "Why ***I*** don't read your code comments".