Commenting vs Documenting

Commenting is a translation between two languages that developers know, aiming to ease the understanding of a behavior.

Documenting is different, it is about requirements and modularity, and it is (almost) always good to have, especially when dealing with teams. The general fear of over-documentation is so rare that it became a myth. Patterns like JSDoc are ways of documenting your code, not commenting.

For example, this is a documentation:

/**
 * Get the content from ID.
 * @param {Object} event The event object.
 * @param {Object} body The body of the request.
 * @returns {Promise}
 * @see {@link module:services/content/catalog}
 */
function getStuff(event, body){
  //...
}

This is a comment:

// If the objects are the same, throw error 542
JSON.stringify(obj) === JSON.stringify(obj2) && throw new SystemError({ code: 542 })

So, when to comment?

When a verbose version of your code is not enough to describe its behavior. When understanding it in plain-English is significantly faster than in code.

Why?

Programming is like writing a text: The comprehension is subjective. It may vary due to numerous factors: region, subject, epoch, cultural factors. The understanding about the code may vary between new developers and old-school developers, between a REST developer and an Event Driven, between people who had a CS/engineering courses and those who don't.

Other developers will consume your comment before they consume the code, so it can speed up things up. If I need to refactor a code and your complicated line is not the place that I need to take a look, I will skip it.

But why this is important at all?

Speed.

Gifted minds commonly dislike commenting and documenting due to the fast way that they think. They are very productive - when assigning the sheer number of complex features that they can pull in a short time - but they struggle to scale when working with other developers. This can even be a major problem, since they feel that they are not being productive when slowing down to assist others.

If you want to know how extremely genius people write insane on-liners to abstract a whole component, you can join CodeSignal, enroll on any code challenge and take a look into the top answers. A code-base created like that and without comments or documentation will be simply unmaintainable.