JavaScript Comments

Comments are notes written inside your code for humans. JavaScript ignores them when executing the program.

// This is a comment

JavaScript supports two forms: single-line comments that start with //, and multi-line comments wrapped in /* and */. Comments do not run as JavaScript code.

Comments explain intent, reasoning, assumptions, unusual behavior, important constraints, or decisions that are difficult to understand from the code alone.

const timeout = 5000;

// Give the server enough time to finish processing before retrying.
setTimeout(loadResults, timeout);

Important: comments remain part of the source code and may be shipped to browsers. Never put passwords, API keys, access tokens, or private information in comments.

A single-line comment starts with //. Everything after the two slashes on that line is ignored by JavaScript.

// This is a single-line comment

const age = 30;
const score = 95; // User's score

Inline comments can be useful for short context, but too many can make a line harder to scan.

A multi-line comment starts with /* and ends with */. Everything between those markers is ignored by JavaScript.

/*
  Give the retry logic a short recovery window.
  The API may still be processing the latest request.
*/
setTimeout(loadResults, 1000);

Use this form for longer explanations, assumptions, or non-obvious logic. Version control such as Git is better for preserving old code than leaving large blocks commented out.

A good comment adds information that the code does not clearly show. It may explain why a business rule exists, what assumption must remain true, an unusual approach, an external constraint, or a trade-off.

// Give the server a short recovery window before showing an error.
setTimeout(loadResults, 1000);

“Wait 1 second” describes what the code already says. The first comment preserves the reason. Do not comment what the code clearly tells the reader.

// Bad: the code already says this.
// Add 1 to the retry count
retryCount += 1;

// Better: explain the reason the reader cannot see.
// Retry once because the API may still be indexing the latest data.
retryCount += 1;

function getVisibleProducts(products) {
  // Keep discontinued products out of the customer-facing list.
  return products.filter(product => product.isActive);
}

The useful comment gives the product context behind the filter. The main rule is to explain intent, reasoning, assumptions, or constraints rather than narrate obvious syntax.

1. Narrating every line: // Increment i adds noise when i++ is already clear.
2. Stale comments: update or remove a comment when code changes.
3. Commented-out code: use Git to preserve old implementations.
4. Huge essay comments: move detailed decisions to documentation or a decision record.
5. Secrets in comments: never include passwords, keys, tokens, or private data.
6. Blaming people: explain the technical constraint, not who wrote the old code.

Remember: if changing the code would make the comment false, update the comment or remove it. A wrong comment can be worse than no comment because it actively misleads the reader.

Read about Comment Coding Guidelines

Before adding a comment, ask whether a clearer name, smaller function, or simpler control flow would explain the code more reliably. Clear code and useful comments work together.

// Check if user is allowed to purchase
if (u.a > 17 && u.s === "active") {
  purchase();
}

const isEligibleToPurchase =
  user.age > 17 && user.status === "active";

if (isEligibleToPurchase) {
  purchase();
}

The descriptive name makes the condition easier to understand. Add a comment too when there is important business context the code still cannot express.

JavaScript also supports a special documentation style called JSDoc. It commonly documents functions, parameters, return values, expected errors, and public APIs.

/**
 * Calculates the final price after applying a discount.
 * @param {number} price - The original price in dollars.
 * @param {number} discount - A decimal between 0 and 1.
 * @returns {number} The discounted price.
 */
function applyDiscount(price, discount) {
  return price * (1 - discount);
}

• /** ... */ marks a documentation comment.
• @param describes a parameter.
• @returns describes the returned value.

Editors and documentation tools can use JSDoc to provide helpful information. JSDoc is still a comment: it does not validate runtime values, enforce types at runtime, or change JavaScript execution. Use runtime validation or TypeScript when the program must enforce a rule.

Best practice: keep JSDoc close to the function, document public or confusing APIs first, and explain the contract callers need to know instead of repeating a function name.

1. Write a single-line comment explaining what the next line does.
2. Write a multi-line comment containing two lines of explanation.
3. Which is more useful: // Add 1 to retryCount or // Retry once because the API may still be processing the request.? Explain why.
4. Does // Calculate total add useful information before const total = price * taxRate;?
5. Write a JSDoc comment for function add(a, b) { return a + b; }.

• JavaScript ignores comments during execution.
• // creates a single-line comment; /* */ creates a multi-line comment.
• Useful comments explain intent, reasoning, assumptions, or non-obvious behavior.
• Avoid comments that repeat obvious code, and keep comments synchronized with code.
• Remove commented-out old code and use version control instead.
• Never put secrets in comments.
• JSDoc documents functions and APIs for humans and tools, but does not change runtime behavior.

Now that you know how to add useful notes and documentation to your code, let's learn about JavaScript statements and how they form the instructions your program executes. Continue to JavaScript Statements.

• What purpose do comments serve in JavaScript?
• How do you create a single-line comment in JavaScript?
• How do you create a multi-line comment in JavaScript?
• What are best practices for useful comments?
• What conventions help comments remain maintainable?