Are Comments a Waste of Time?

[Glen Kunene]

How useful to you are code comments? Do you write them only out of habit or
do you believe they serve an important function?

http://www.java-zone.com/free/articl...Kabutz06-1.asp

Let us know.

Glen Kunene
Senior Editor
DevX.com

[Prashant]

Hi,
I think comments play an important role in Explaining code to someone
who has not written it and it hardly takes any time.When i go through some
third party code , The comment itself makes it easy to understand the code
otherwise would be quite a task to understand it.I agree that some comments
on like get and set methods seems useless , but then it is always good to be
explicitly mention it.
Prashant

"Glen Kunene" <gkunene@devx.com> wrote in message
news:3c890740$1@10.1.10.29...
> How useful to you are code comments? Do you write them only out of habit
or
> do you believe they serve an important function?
>
> http://www.java-zone.com/free/articl...Kabutz06-1.asp
>
> Let us know.
>
> Glen Kunene
> Senior Editor
> DevX.com
>
>

[John Butorac]

To understand and be able to maintain code that wasn't written by you, it is
essential that code is properly documented. I believe that it is arrogant
to believe that your code is easily understood by all that come after you.
First, you have no idea of the relative skill level of the developer that
will come behind you to maintain your code. Second, just b/c it seems
obvious to you that doesn't necessary mean the logic that you used to tackle
a particular problem makes sense to others. In my opinion, proper
documentation doesn't only include comments throughout the code that you
write, but design documentation that explains to other developers the
challenges that you faced and the logic that you developed to effectively
address those issues.


"Glen Kunene" <gkunene@devx.com> wrote in message
news:3c890740$1@10.1.10.29...
> How useful to you are code comments? Do you write them only out of habit
or
> do you believe they serve an important function?
>
> http://www.java-zone.com/free/articl...Kabutz06-1.asp
>
> Let us know.
>
> Glen Kunene
> Senior Editor
> DevX.com
>
>

[Jim Napoleon]

Commented code is very important. The trick is to make the comments precise
and to the point. I have seen much "commented" code in my years as a software
developer. The most fustrating to me is to see this large comment at the
head of a file that goes on and on like a disertation for a thesis and takes
up half or more of an 8 1/2 by 11 page. I have seen the spectrum of someone
commenting on every line of code to no comments at all.

The kind of comments that are very useful are the ones that document what
the parameters of a function are supposed to mean, and what the local variables
mean and how they are to be manipulated, and what the return value of the
function means. The local variables I mean are the non-obvious ones, like
i,j,k,m,n, etc., which are normally used for indexing something, like an
array or perhaps a matrix.

Sometimes the variables themselves can be self-documenting. During one of
my companies' attempts at ISO9000 certification, a collegue of mine suggested
that the code itself can meet some of the documentation requirements of ISO9000.
Variable names like "temperature_at_inlet", rather than just "temperature1"
can go a long way with understanding the code.

In closing, always remember and never forget; when you change the code, BE
SURE TO CHANGE THE COMMENTS ACCORDINGLY. I can't tell you how many times
I have come across software code with comments that degenerated into a meaningless
waste of the ASCII code. So that I could understand what the software does,
I have had to remove these confusing comments, analyse the code (usually
legacy code that has not been looked at for a while), and put in the comments
again so that someone else will have a chance of understanding what the code
does. This is not an efficient use of a developer's time. The kind of comment
I just love is the kind that is listed at the start of the file with a section
like "Revision:". At item number 53, it is written; "Made numerous changes
- by Developer Foo". Looking for Developer Foo's changes is like taking
a stroll through the Amazon looking for buried treasure with a faded treasure
map. Not a trail or comment relative to item 53 can be found.

I could go on and on. All I can say is; be kind to your fellow collegues
and document properly. If your company has a policy with respect to comments,
follow them. Otherwise, just use common sense. If you are designing a very
complicated algorithm, for example, solving Schroedinger's Wave Equations,
lots of comments would probably be necessary. If you are simply modifying
a Quicksort algorithm, just a few comments will probably be OK.

Have a good one.

Jim

"Glen Kunene" <gkunene@devx.com> wrote:
>How useful to you are code comments? Do you write them only out of habit
or
>do you believe they serve an important function?
>
>http://www.java-zone.com/free/articl...Kabutz06-1.asp
>
>Let us know.
>
>Glen Kunene
>Senior Editor
>DevX.com
>
>

[Dtr. Mike Nesel]

Books are a waste of time, too!

This is so, because I don't like books. They are often so useless that I
usually don't read them. Ever since my older brother caught me reading Green
Eggs and Ham as a child and then broke the news to me that it was absolute
fiction, I've developed a keen distrust of books. This opinion only solidified
when I pursued my computer science degree. I realized that my classmates
and I read books only to earn good marks from mean-spirited instructors who
were more concerned with how many books we read rather than whether or not
we really understood them! Simply put, I felt that books were a waste of
time.

Dtr. Mike Nesel, PhDSt, MDD, MsS, FS

[Paul Clapham]

I usually don't write many comments, on the theory that the code should
explain itself. And most code does. However, when I find myself writing
ugly or convoluted code, I also find myself writing comments to explain it
(and to apologize for it). Or -- as Dr. Kabutz alludes to -- if I have
unfinished business, I'll make a note in the code.

I have recently been working on some code that I wrote several months ago --
uncommented, of course -- and finding it difficult to maintain. But
thinking about comments in that context, I realize that the comments that I
and most other programmers would have written would have been of little use.
I had questions like "why does this class have a remove() method and a
close() method, what's the difference, and which should I modify?" I would
bet that the comments you would have found written by someone who believed
in them would have said something like this:

public void close()
/** Closes the component by making it invisible **/

public void remove()
/** Removes the component from the tree of displayable panels **/

No hint of why they are separate methods or which you should override if you
want to have something cleaned up when the system is finished with the
component. But of course the design is documented somewhere else, isn't it?

[Tracy Barlow]

"Glen Kunene" <gkunene@devx.com> wrote:
>How useful to you are code comments? Do you write them only out of habit
or
>do you believe they serve an important function?
>
>http://www.java-zone.com/free/articl...Kabutz06-1.asp
>
>Let us know.
>
>Glen Kunene
>Senior Editor
>DevX.com
>
>

I've been a programmer for 23 years, I started with COBOL and BASIC, and
now develop mostly in VB. I find, in most cases, that if I am having trouble
working out what's going on by reading the code, then the comments rarely
if ever shed any light on the it.

I was taught, as a COBOL programmer, to make my code self documenting, using
variable names etc that described their purpose. So I rarely use comments.

In my opinion Tutors, lecturers, teachers of computer science, who insist
on extensive comments within the code are out of touch with the reality programming.

[David D. Cruger]

Mr Kunene is so way off base it's unbelievable. I have been programming for
the past 18 years and the one absolute thing I have learned is that comments
can save you time, BIG TIME. Trying to figure out what is suppose to happened
in a block of code that was written 8 years ago that doesn't have comments
can be a mind bending experience. Even code you wrote your self. Why the
heck did I do that?

I believe a better statement to make about comments is this: I don't hate
comments I hate bad comments. You can apply the same statement to code:
I don't hate code I just had bad code.

Comments are not just used to indicate what a certain function does but a
function comment header can give details about code migration. Modify dates,
by whom and why, bugs that might have been fixed. These are very valuable
pieces of information. Comments, well formatted ones, can also help break
up code to make it more readable. Then you have module headers to indicate
what the class or module is going to do...etc

With all that being said I can make this statement. Good code can stand
somewhat on its own with out comments. However even slightly bad code I
would prefer to even have bad comments than none at all.

Keep the comments going.

David D. Cruger

[David Browning]

"Glen Kunene" <gkunene@devx.com> wrote:
>How useful to you are code comments? Do you write them only out of habit
or
>do you believe they serve an important function?
>
>http://www.java-zone.com/free/articl...Kabutz06-1.asp
>
>Let us know.

I have to agree with Dr Kabutz. choosing sensible, descriptive names (ie
which capture the purpose of the method or variable) pretty well negates
the reason for comments. Programs can be almost self-documenting. It reduces
the amount of 'typing' significantly; makes maintenance much easier and helps
to focus on each method doing only one thing.

When I'm faced with maintaining commented code, I usually find it necessary
to change method/variable names to encapsulate the description in the comment,
simply to be able to understand the code!

[David Salahi]

"Glen Kunene" <gkunene@devx.com> wrote:
>How useful to you are code comments? Do you write them only out of habit
or
>do you believe they serve an important function?
>
>http://www.java-zone.com/free/articl...Kabutz06-1.asp
>
>Let us know.
>
>Glen Kunene
>Senior Editor
>DevX.com
>
>

Dr. Kabutz' article on comments was a fairly snide attack on a straw man.
Of course, no one is interested in reading inane comments or comments which
are so obvious they could have been generated by a wizard.

But what about well-written comments? Maybe the problem is that so few programmers
write good comments that Dr. Kabutz has rarely seen any well-written comments.
I think that more emphasis needs to be placed on teaching programmers how
to write good comments.

Personally, I do write comments and as time goes by (25 years in this business
now), I continue to become more convinced of the value of good comments.


For example, what a function does is often different than how it does it.
One good use of comments is to document the overall purpose of a function.
Often, it's difficult to tell what a function is actually accomplishing by
wading through the individual lines of code.

Comments can also be very valuable in giving context. I.e., it may be helpful
to explain how a particular function fits into the big picture, when it is
called, what the end-user is trying to accomplish at that time, what the
data should look like, etc.

Another good purpose of comments is to save time. Instead of spending five
minutes studying a function, I could spend 15 seconds reading a comment.


Kabutz makes one good point, though: make code self-documenting as much as
possible and you will reduce the need to write and maintain comments.

[Russell P. Holsclaw]

I found the article very unconvincing. Although it's true that bad comments
are sometimes worse than no comments at all, sometimes things need
explanation.

In the examples given in the article, it occurred to me on reading it that
the code in the getName() method was simply a "placeholder", or "stub
procedure" to be replaced at some future time by a method that actually
returned a real name, instead of an uninformative message.

In a sense, however, what comments there were helped me to realize that,
although they should have said so explicitly. Obviously, the author of the
article didn't pick up on that at all, or he would have mentioned this.

In my own experience as a programmer, I've found that the best approach to
commenting is to pretend you are explaining the code to someone who's
looking over your shoulder at it, (perhaps someone who's going to take over
the code as soon as you go outside and get run over by a bakery truck) and
write into the comments whatever you would have told that person.

[I think the parody of the article written by "Dtr Mike Nesel" pretty well
captured my own gut reaction to the article. It was an exercise in
arrogance. I was expecting to read an extensive treatise on the difficulties
of maintaining sync between code and comments, but the article turned out to
be completely devoid of such subtlety. Publishing it was a poor editorial
decision, perhaps influenced too heavily by the author's advanced degree.]

--
Russ Holsclaw

[N Nguyen]

"Glen Kunene" <gkunene@devx.com> wrote:
>How useful to you are code comments? Do you write them only out of habit
or
>do you believe they serve an important function?
>
>http://www.java-zone.com/free/articl...Kabutz06-1.asp
>
>Let us know.
>
>Glen Kunene
>Senior Editor
>DevX.com
>
>

This article is what an arrogant nonsense opinion on programming would be
like. As for the author, I would urge him to go to www.literateprogramming.com
to read Knuth’s thinking about commenting code.

From the NW.

[Mike Stillman]

Some thoughts from a Sr. Technical Writer at a major
Web software company:

* Amazing Andrea won't always write the code for the
ScheduleWizard 3000's autocomplete feature. She could
move onto another module, project, company, or, as
another poster said, get hit by a bakery truck. At some
point, someone else, not necessarily a programmer, will
likely have to work with this code. Sensibly named
variables and well written comments will be essential for
that person.

* Sure, some uncommented code requires minimal time to
understand. However, if the developer invests a small
percentage of the time writing good comments, this should
be a great ROI in time saved for others.

* Sometimes good coders don't make good writers, and vice
versa.

* Hmm, maybe I should develop a course on Code Commenting!

[Steve Schmitt]

No, comments are not a waste of time - if they are meaningful. Mr. Kabuts
is correct that many comments are written just to make the code look commented.
But sometimes they can be benificial.

For example, if your method returns a collection, the method signature doesn't
tell anyone what's inside. So you might have a JavaDoc comment like this:
<code>
/** Returns an ArrayList of HashMaps that defines the presentation.
* Each HashMap contains PresentationWidget objects, keyed by the
* Integer presentationAreaId
*/
</code>
This reveals the otherwise obscure contents of the returned ArrayList.

Inline comments are often useless, if they simply echo what the code is doing.
The classic useless inline comment something like this:
<code>
packet += 2; // increment packet by 2
</code>
Thank you, Mr. Programmer, we know what the += operator does! But if the
comment tells us <b>why</b> we're doing that, it might be useful:
<code>
packet += 2; // skip odd packets, since they contain useless spaces
</code>

If someone is using a class you have written, good comments can help them
use it properly. If someone is modifying a class you have written, good
comments can keep them from screwing it up. Think about this, and only write
comments that will actual be useful.

[CliffordEW]

I am sharing this article with my class on "Application Programming". I am
one of those "mean-spririted" teachers that require too many comments. His
second bulleted reason for disliking comments is very good. It is a mistake
to write comments that tell what the code does. The code itself must be
written to tell the reader what the code does. If it doesn't the code needs
to be rewritten. Good, worthwhile comments tell why the code does what it
does. And sometimes, they tell what the code ought to do, but doesn't yet.
But in that case the code should be changed. Not left wrong through release
after release.