The Good And Bad Of Adding Comments To Code

If you've heard something like this before, please stop me...

“Good code is self-documented.”

This is the phrase I've heard the most during the last few years of programming code for a living.

It's an overused expression.

It also has a kernel of truth, as do many clichés. However, this reality has been exploited to the point where most individuals who use the term have no concept of what it means.

Is this accurate? Yep!

Does this imply that your code should never be commented? Nope.

We'll go over the good, bad, and ugly of commenting on your code in this post. To begin, code comments may be divided into two categories. Documentation and clarifying remarks are what I call them.

DOCUMENTATION COMMENTS

Comments in the documentation are for those who are likely to consume your source code but not read it. You'll need API documentation if you're creating a library or framework for other developers to utilise.

Your API documentation is more likely to become obsolete or wrong over time if it is separated from the source code. To avoid this, consider embedding the documentation directly in the code and then extracting it with a tool.

Example:

// Load the full build.
var _ = require('lodash');
// Load the core build.
var _ = require('lodash/core');
// Load the FP build for immutable auto-curried iteratee-first data-last methods.
var fp = require('lodash/fp');

// Load method categories.
var array = require('lodash/array');
var object = require('lodash/fp/object');

// Cherry-pick methods for smaller browserify/rollup/webpack bundles.
var at = require('lodash/at');
var curryN = require('lodash/fp/curryN');

When writing documentation comments, make sure they follow a consistent format and are clearly distinct from any inline explanation comments you might wish to include.

CLARIFICATION COMMENTS

Clarification comments are for anybody who may need to maintain, refactor, or expand your code in the future (including yourself). A clarifying comment is frequently a code smell. It informs you if your code is overly complicated. Instead of using clarifying comments, you should try to simplify the code.

“good code is self-documenting.”

Here's an example of a poor — yet hilarious — clarifying comment.

/* 
 * Replaces with spaces 
 * the braces in cases 
 * where braces in places  
 * cause stasis.*
 */ 
$str = str_replace(array("\{","\}")," ",$str);

Rather than adorning a little perplexing statement with a brilliant rhyme — in amphibrach dimeter, no less — the author could have spent more work developing a function that makes the code itself easier to read and comprehend. Perhaps a procedure called removeCurlyBraces is called from a function called sanitizeInput? Don't misunderstand that infusing a little humour may be beneficial to the soul at times, especially when you're trudging through a punishing assignment. When you add a hilarious comment to compensate for faulty code, however, it actually discourages others from refactoring and fixing the code afterwards.

Do you truly desire to be the one who deprives all future coders of the delight of reading that witty little rhyme? Most hackers would giggle and walk on, dismissing the code stench.

There are instances when a statement is superfluous. There's no need to add a remark if the code is already straightforward and apparent.

Don't do something like this:

/*set the value of the packages integer to 53*/
int packages = 53;

Nonetheless, there are situations when, no matter what you do to the code, a clarifying remark is still required. This usually occurs when you need to provide context for a non-intuitive approach.

Here's a nice example:

function addSetEntry(set, value) {
  /*    Don't return `set.add` because it's not chainable in IE 11.  */
  set.add(value);
  return set;
}

There are other occasions when, after much thinking and trial, it is discovered that the seemingly simplistic answer to a problem is actually the best. In certain cases, it is nearly unavoidable that another developer will come along believing they are much wiser than you and start fiddling with the code, only to realise that your approach was the best way all along.