Code Commenting Clarified

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

A repost of my past article on Medium

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

Story 1: A valuable lesson a Uni Professor gave to a student

I read this from a book many years ago, pity, I forgot the name.

One day, a high-achieving student came to one professor’s office to complain about the score of an assignment. He said, “My result was correct. How could I only get 60% marks on this assignment?”

This professional smiled and said, “Yeah, your result is correct. Let me show the version that received 100% marks first”.

The student came towards to read the code on the screen, and was puzzled. “His solution is exactly the same as mine.”

The professor said, “You read and understood his code quickly, probably a few seconds, right? Codewise, about the same. But you wrote one and a half pages of Java Doc.”

Story 2: Ruby code

Ruby language, was created by Matz and has been widely used in Japan. Ruby was made to the English-speaking world by the famous “Programming Ruby” (aka The Pickaxe) book by Dave Thomas and Andy Hunt (both the co-authors of Agile Manifesto), in 2008.

I read about how Dave Thomas and Andy Hunt discovered Ruby. After being impressed by Ruby’s syntax, they read the source code (Ruby is open-source). Dave and Andy were deeply impressed by the code quality. They could read the code, not relying on the sparse comments in Japanese (which they did not understand).

This is an excellent example of a top programmer writing code differently from the mass.

By the way, I was honoured to receive the Ruby award (for my open-sourced BuildWise CT Server) from Matz in 2008 in Japan. In a way, my coding style is ackownledged by one of the best in the world. Matz is a nice person, every easy to talk to, and his opinions are practical and visionary. Matz guarded the beautiful Ruby language from bad stuff, such as annotations, type-script and Promises in JavaScript (see here), which seemed good ideas at the time.

“Most of the new parts” in JS belong to “Bad Parts”, by Douglas Crockford, the author of “How JavaScript Works”, source

a annotations is one of main reasons for me to stop using Java.

My Opinions on Code Comment