When Are Code Comments Helpful? Best Practices for Clean JavaScript

In this article we discuss the controversial topic of code comments for developers writing clean code.

Some argue that commenting is a good practice, while others claim it is unnecessary.

There are no absolute rules; often comments add little value because modern tools provide better alternatives, and in some cases they can even hinder readability, making the absence of comments the best practice.

Conversely, comments can be useful, for example when public API documentation explains usage but not internal logic.

Below we summarize common commenting approaches and how to avoid harmful ones to improve code quality.

Only comment complex business logic

The purpose of comments is to help programmers understand the program or business logic, especially when the logic is complex. However, comments usually do not describe algorithms; the code itself should be clear. Good code is self‑explanatory, but adding comments for particularly opaque business rules—such as credit‑card or insurance logic—can be helpful.

function convert(data) {
  // The result
  let result = 0;

  // length of string
  const length = data.length;

  // Loop through every character in data
  for (let i = 0; i < length; i++) {
    // Get character code.
    const char = data.charCodeAt(i);
    // Make the hash
    result = (result << 5) - result + char;
    // Convert to 32-bit integer
    result &= result;
  }
}

The above code contains many comments that add noise; the cleaner version is:

function convert(data) {
  let result = 0;
  const length = data.length;
  for (let i = 0; i < length; i++) {
    const char = data.charCodeAt(i);
    result = (result << 5) - result + char;
    result &= result; // Convert to 32-bit integer
  }
}

Avoid log‑type comments

Log‑type comments that record dates were once useful before version‑control tools existed, but now such information belongs in the VCS (e.g., git log). Keeping these comments adds redundancy and reduces cleanliness.

Example with log‑type comments:

/**
 * 2018-12-20: Removed monads, didn't understand them (CC)
 * 2018-10-01: Improved using special mondas (JS)
 * 2018-02-03: Removed type‑checking (LI)
 * 2017-03-14: Added add with type‑checking (CC)
 */
function add(a, b) {
  return a + b;
}

function add(a, b) {
  return a + b;
}

Avoid using comments to mark positions

Position‑marking comments increase redundancy. Proper naming and code organization improve readability without such markers.

Example with position markers:

///////////////////////////////
//  Controller Model Instantiation
///////////////////////////////
controller.model = {
  name: 'Felipe',
  age: 34
};

///////////////////////////////
//  Action Setup
///////////////////////////////
const actions = function() {
  // ...
};

controller.model = {
  name: 'Felipe',
  age: 34
};

const actions = function() {
  // ...
};

Summary

Whether to add comments remains one of the most debated topics among software developers; extremes are rarely optimal.

This article highlighted three practices: comment only complex business logic, avoid log‑type comments, and avoid position‑marking comments. For public APIs, comments can serve as useful documentation.

A common bad habit is commenting every line, which many beginners adopt as a form of note‑taking.

Distinguishing between learning notes and code comments is crucial and should not be conflated.

Key takeaways:

Only comment complex business logic

Avoid log‑type comments

Avoid using comments to mark positions