Don’t Pad Your Comments

So I met this comment the other day^†:
^{†anonymized and exaggerated for entertainment purposes}

Don’t write comments like this. Let’s break this down:

“The purpose of an objective highlighter is to highlight the relevant objectives.”

First off, we are in the <summary> tag — this is, by definition, the purpose. It’s pointless to state in the primary comment what it is describing. Examples include: “This field is for ..”, “This class serves as an ..”, “This variable controls how ..”, etc. Describe what the identifier does. In other words:

“The objective highlighter highlights the relevant objectives.”

Immediately, we can see the second issue. The comment just restates that it is about the objective highlighter, when we already know this from the class name — this is what the <summary> is for, again, by definition. So let’s get rid of that too:

“Highlights the relevant objectives.”

Before we get to the elephant in the room, let’s talk about “relevant”. It’s anything but relevant in this comment (har har). The word adds no additional information and, worse yet, might even cause confusion (are there irrelevant objectives to this class?). In other words, skipping the word changes nothing:

“Highlights the objectives.”

And we’re down to the final problem. The programmer would read the identifier name, then the comment. If the identifier is well-named (and, let’s just assume that they are without getting into identifier naming), then it already describes its purpose in the most suitable manner possible. It says what it does (“highlights”) and, in addition, who it does this to (“objectives”). So this comment is completely redundant. Voilà:

Huh. We just deleted the comment.

Yes, because the comment failed to answer the first question comments are supposed to answer: Why? and all the consequent elaboration.

Writing good comments is an art. It’s not easy. But writing bad comments is avoidable. It’s much easier — don’t write anything, when writing something doesn’t add any value. Writing comments is much like the beginner writing tips — keep trimming the padding until only the substance is left.

Okay, for completeness, let’s write a decent (and completely bogus) comment for the class:

Mic drop.

P. S. I thought about naming this post “Don’t Write Comments”, but I didn’t want to get banned from the Internet.