Code Commenting Clarified

Generally speaking, the less, the better if you do know how.

This article is one of the “IT Terminology Clarified” series.

Table of Contents:
· Two Stories about Code Comment
∘ Story 1: A valuable lesson a Uni Professor gave to a student
∘ Story 2: Ruby code
· My Opinions on Code Comment
∘ 1. Prefer better design than explaining
∘ 2. Writing good comments is not easy
∘ 3. Incorrect comment is worse than no comment
· My specific advice

In code review (this was me working as a Java Tech lead, before switching day-time work to test automation and Continuous Testing), novice programmers often said my code was “lacking comment”. What they really meant was, “I did not write the full JavaDoc” like below:

/**
 * Constructor.
 */
public Resource() { ... }

/**
* Set the tool tip text
*
* @param text  the text of the tool tip
*/
public void setToolTipText(String text) {
   
}

Obviously, this above JavaDoc is bad (i.e. unnecessary), even novice programmers can probably tell. In practice, these kinds of comments are still quite common.

Before I share my opinion on commenting, let me ask you a question, “Do you know anyone who always does these (document every parameter, returns) diligently?” (here, I mean, every Java method in all code). The answer is most likely “No”, which means there is not much value in bringing strict Javadoc in code review (because few are disciplined to do that).

I do know one, though, and the only one I met over ~10 years working in Java. This person was my colleague at DSTC, David Holmes, a co-author of The Java Programming Language, 3rd edition (one of the other two authors is James Gosling, the creator of Java). When the two of us worked together, I was deeply impressed with his discipline on JavaDoc. He wrote high-quality comments.

Generally, I write as few comments as possible, coding in a way that avoids excessive explanation.

Two Stories about Code Comment