Skip to content

Comments and Readability

Learn how to write code that humans can read: comments, naming, formatting, and when not to comment.

What you'll learn

  • The three types of comments and when to use each
  • Why good naming reduces the need for comments
  • How to write comments that explain 'why', not 'what'
  • Formatting conventions that improve readability
  • The relationship between readability and maintainability

Concept

Comments and Readability

Readability is the measure of how easily a human can understand your code. Programs are read far more often than they are written — sometimes by others, sometimes by you months later. Code that is easy to read is easier to debug, easier to extend, and less likely to harbor bugs. Writing readable code is a professional skill, not an optional nicety.

Types of Comments

Most languages support single-line comments (// in JavaScript) and multi-line comments (/* ... */). JavaScript also has JSDoc comments (/** ... */) that document function signatures for tools and editors:

// Single-line: a brief note

/* Multi-line: use for longer
   explanations that span lines */

/** JSDoc: documents a function for tooling
 * @param {number} price - the item price
 * @returns {number} the price with tax
 */

Comment the Why, Not the What

The most common commenting mistake is describing what the code does — which the code already shows. Good comments explain *why* the code does something: the business reason, the workaround, the constraint:

// BAD: describes what the code already says
const total = price * quantity;  // multiply price by quantity

// GOOD: explains the why
const total = price * quantity;  // bulk discount applied at checkout

Naming as Documentation

The best comment is a well-chosen name. When you name a variable daysSinceLastLogin instead of d, the code documents itself. When you name a function isEligibleForDiscount instead of check, the intent is clear without a single comment. Good naming eliminates most comments. Reserve comments for the cases where the code genuinely cannot speak for itself — non-obvious algorithms, external constraints, or bug-fix workarounds.

Formatting Conventions

Consistent formatting makes code scannable. Follow these principles:

  • Indent consistently — 2 or 4 spaces, pick one and stick with it.
  • Keep lines short — under 80–100 characters so code fits on screen.
  • Group related statements — blank lines between logical sections.
  • Align operators in long expressions for visual scanning.

Most teams use a formatter (like Prettier) to enforce these automatically, so you can focus on the logic instead of the layout.

Readability vs. Cleverness

Resist the urge to write "clever" one-liners that are hard to understand. A five-line solution that is obvious is better than a one-line solution that requires five minutes to decode. Code is a communication tool, not a puzzle. The smartest code is the code that the next reader understands fastest.

Example

              // BAD: unclear naming, redundant comments, poor formatting
function p(d){let t=0;for(let i=0;i<d.length;i++){t+=d[i].p*d[i].q}return t} // calc total

// GOOD: clear naming, comments only where needed, readable format
function calculateOrderTotal(items) {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
  }
  return total;
}

// Comment explaining a non-obvious business rule:
function applyShipping(total) {
  // Free shipping threshold was raised from $50 to $75 in Q3 2024
  if (total >= 75) return 0;
  return 5.99;
}

// JSDoc for public API functions:
/** Calculate the total cost of an order including shipping.
 * @param {Array} items - array of {price, quantity} objects
 * @returns {number} total cost in dollars
 */
function checkout(items) {
  const subtotal = calculateOrderTotal(items);
  const shipping = applyShipping(subtotal);
  return subtotal + shipping;
}
            

The bad version is a single line that is nearly impossible to read. The good version uses descriptive names, only comments the non-obvious business rule, and includes JSDoc for the public function.

Try it

  • Markdown Previewer

    Good documentation uses Markdown for formatting. Preview your README and comment-style docs here.

  • Code Diff

    Compare two versions of code — a practical way to see how readability improvements change a file.

Common mistakes

The mistake

Writing comments that just restate the code.

The fix

If the comment says the same thing as the code, delete it. Use comments to explain intent, constraints, or non-obvious reasons — not to narrate syntax.

The mistake

Using abbreviations or single-letter variable names to save typing.

The fix

You read code ten times more than you write it. Type the full name: customerEmailAddress, not cea. Your IDE's autocomplete makes long names cost nothing.

The mistake

Leaving commented-out code blocks in the codebase.

The fix

Delete dead code. Version control (Git) preserves history — you can always retrieve old code. Commented-out blocks clutter the file and confuse readers.

Related Cheatsheets

Practice Comments and Readability

3 exercises

Practice Comments and Readability

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors