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())