Handling Comments in Code: 4 Essential Rules from clean-code-javascript

The clean-code-javascript repository advises treating comments as a safety net for complex business logic that cannot be made self-evident through naming and structure, while strictly eliminating commented-out code, journal entries, and visual markers.

The ryanmcdermott/clean-code-javascript style guide is a widely-adopted resource for writing maintainable JavaScript. When handling comments in code, the guide emphasizes that expressive variable names and clear functions should replace most explanations, reserving comments solely for non-obvious implementation details.

Comment Only Business Logic Complexity

According to the guide in README.md at line 2223, you should add comments only when the why behind a piece of code cannot be expressed succinctly by the code itself. This approach keeps the codebase lean and prevents stale or redundant explanations.

Consider this over-commented function that states the obvious:

function hashIt(data) {
  // The hash
  let hash = 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
    hash = (hash << 5) - hash + char;
    // Convert to 32-bit integer
    hash &= hash;
  }
}

The improved version removes noise and retains only the explanation for the non-obvious bitwise operation:

function hashIt(data) {
  let hash = 0;
  const length = data.length;

  for (let i = 0; i < length; i++) {
    const char = data.charCodeAt(i);
    hash = (hash << 5) - hash + char;

    // Convert to 32‑bit integer (required for consistent hashing)
    hash &= hash;
  }
}

Remove Commented-Out Code Entirely

As documented at line 2268 of README.md, you must never leave commented-out code in your codebase. Rely on version control (Git) to retrieve old implementations. Dead code creates noise, risks accidental re-introduction of broken logic, and obscures diffs.

Bad practice with dead code:

doStuff();
// doOtherStuff();
// doSomeMoreStuff();
// doSoMuchStuff();

Clean implementation trusting Git history:

doStuff();

Eliminate Journal Comments

The guide explicitly prohibits journal-style comments at line 2889. Do not embed dates, author initials, or change-log notes inside source files. Use git log instead to prevent files from becoming manual changelogs cluttered with outdated information.

Avoid this pattern:

/**
 * 2022-01-15: Refactored loop (AB)
 * 2021-12-03: Fixed off‑by‑one bug (CD)
 */
function combine(a, b) {
  return a + b;
}

Prefer clean code without inline history:

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

Avoid Positional Markers

At line 3179, the guide advises against using long lines of slashes or other symbols to separate sections visually. Instead, rely on proper naming, indentation, and automated formatting tools like Prettier or ESLint for visual structure.

Remove visual clutter like this:

//////////////////////////////////////////////////////////////////////////////
// Scope Model Instantiation
//////////////////////////////////////////////////////////////////////////////
$scope.model = { menu: "foo", nav: "bar" };

//////////////////////////////////////////////////////////////////////////////
// Action setup
//////////////////////////////////////////////////////////////////////////////
const actions = function() {
  // …
};

Trust naming conventions and formatting:

$scope.model = { menu: "foo", nav: "bar" };

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

Summary

• Reserve comments for business logic complexity that cannot be expressed through self-documenting code, as implemented in the README.md guidelines at line 2223.
• Delete commented-out code immediately and rely on Git history for retrieval, following the rule at line 2268.
• Remove journal comments containing dates or author initials; use git log for tracking changes instead of inline annotations.
• Eliminate positional markers like lines of slashes; depend on proper naming and automated formatting tools for visual organization.

Frequently Asked Questions

When should I add comments according to clean-code-javascript?

You should add comments only when the underlying business logic is too complex to be clear from the code itself, specifically when the why behind an implementation cannot be expressed through naming conventions. The guide at README.md line 2223 emphasizes that good code should be self-explanatory without requiring explanatory text.

Why is commented-out code considered harmful?

Commented-out code creates visual noise in the codebase, risks accidental re-introduction of broken or deprecated functionality, and makes code reviews and diffs harder to read. As noted at line 2268, version control systems like Git provide a safer and cleaner way to retrieve historical implementations.

What are journal comments and why should they be avoided?

Journal comments are inline annotations containing dates, author initials, or change descriptions that document the history of modifications within the source file. They should be avoided because they become outdated quickly and clutter the codebase; the guide at line 2889 recommends using git log instead to track authorship and changes.

How should I organize code sections without positional markers?

Instead of using long lines of slashes or other visual separators to demarcate sections, rely on clear naming conventions, consistent indentation, and automated formatting tools such as Prettier or ESLint. This approach, specified at line 3179, keeps files tidy while maintaining logical structure through code organization rather than visual noise.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}