Lambda the Ultimate

Why I Don't Read Code Comments
started 3/20/2002; 5:40:33 AM - last post 3/20/2002; 11:34:13 AM

Dan Shappir - Why I Don't Read Code Comments

3/20/2002; 5:40:33 AM (reads: 1330, responses: 1)

Why I Don't Read Code Comments

Ever since my older brother caught me typing REM statements into a program as a child and then broke the news to me that they did absolutely nothing, I've developed a keen distrust of comments.

Raise your hand of you remember REM (which continues to work in VB.NET BTW). Makes some good points about comments, with some funny samples from the JDK.

Posted to Software-Eng by Dan Shappir on 3/20/02; 5:41:27 AM

Cimarron Taylor - Re: Why I Don't Read Code Comments

3/20/2002; 11:34:13 AM (reads: 516, responses: 0)

Comments provide a mechanism for communication between developers and are often used to make clear a function’s specification as opposed to its implementation.

For example, suppose someone were to report to me that the getName() method was returning an incorrect value. The comment

/**

* Returns the name of the component given the component index.

* @param idx The component index.

* @return The name of the component at the specified index.

could be very helpful in resolving whether or not the report identified a problem in the implementation as opposed to a problem in the specification or design.

I also find it interesting that Dr. Kabutz fails to mention the common practice of treating comments as metadata. The above comment improves the utility of getName() method in several ways:

1. The comment allows it to be index and searched more effectively.

2. The comment can be formatted into a separate summary.

3. The comment can assist the interactive behavior of an IDE (for instance, in a "tooltip" that appears when the mouse is held over a call to getName())