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.