JavaScript Commenting Best Practices Every Coder Should Know
Master professional JavaScript commenting patterns that improve code readability. Learn when to comment, when not to, and how to write documentation that helps your team and future self.
Knowing the syntax for JavaScript comments is easy. Knowing when and what to comment is the skill that separates amateur code from professional, maintainable codebases. Bad comments are worse than no comments: they mislead readers, go out of date, and clutter the codebase with noise. Good comments explain the reasoning behind decisions, warn about pitfalls, and document the contracts that code cannot express on its own. Combined with proper variable naming conventions, they make codebases significantly easier to maintain.
The best comment is no comment at all, because the code is self-explanatory. The second-best comment is one that explains something the code fundamentally cannot express: a business rule, a performance constraint, a historical reason, or a regulatory requirement. This guide covers the professional commenting patterns that teams at companies with large JavaScript codebases actually follow.
Rule 1: Comment the Why, Never the What
The single most important commenting rule is to explain intent, not mechanics. If your comment restates what the code does, it adds zero information and doubles the maintenance burden:
javascript// BAD: restates the code
// Set the user's name to "Guest"
user.name = "Guest";
// BAD: describes what the loop does
// Loop through each item in the cart
for (const item of cart) {
applyDiscount(item);
}// GOOD: explains WHY
// Anonymize the user's name for GDPR compliance before logging
user.name = "Guest";
// GOOD: explains a business rule
// Apply the holiday discount to all items, even those already on sale.
// Product team confirmed: holiday promotion stacks with existing discounts.
for (const item of cart) {
applyDiscount(item);
}The "what" should come from readable code. The "why" can only come from comments.
Rule 2: Write Self-Documenting Code First
Before writing a comment, ask: "Can I make this code explain itself through better naming, structure, or abstraction?"
javascript// BAD: comment compensates for poor naming
// Check if the user can access the admin panel
const x = u.r === "admin" && u.s === "active";
// GOOD: self-documenting, no comment needed
const canAccessAdminPanel = user.role === "admin" && user.status === "active";// BAD: comment explains a complex condition
// Check if user is eligible for free shipping
if (cart.total > 50 && !cart.hasHeavyItems && user.region !== "international") {
applyFreeShipping(cart);
}
// GOOD: extract to a named function
function isEligibleForFreeShipping(cart, user) {
const meetsMinimum = cart.total > 50;
const noHeavyItems = !cart.hasHeavyItems;
const isDomestic = user.region !== "international";
return meetsMinimum && noHeavyItems && isDomestic;
}
if (isEligibleForFreeShipping(cart, user)) {
applyFreeShipping(cart);
}The Self-Documenting Test
When you write a comment, ask yourself: "Could I eliminate this comment by renaming a variable, extracting a function, or restructuring the code?" If yes, do that instead. If the comment explains business logic, a workaround, or external constraints that code cannot express, keep it.
Rule 3: Document All Non-Obvious Decisions
Some code decisions look wrong unless you know the context. These require comments:
javascript// The timeout is 30 seconds, not the default 5, because the payment
// processor's webhook can take up to 25 seconds during peak hours.
// See incident report: https://internal.example.com/incidents/2026-012
const PAYMENT_WEBHOOK_TIMEOUT = 30000;
// Using querySelectorAll instead of getElementsByClassName because
// the former returns a static NodeList, preventing mutation bugs
// when we modify the DOM inside the loop.
const elements = document.querySelectorAll(".card");
// Sorting by lastName first, then firstName. HR requested this ordering
// to match the format used in their payroll system exports.
employees.sort((a, b) =>
a.lastName.localeCompare(b.lastName) ||
a.firstName.localeCompare(b.firstName)
);Rule 4: Always Comment Regex Patterns
Regular expressions are notoriously difficult to read. Every non-trivial regex should have a comment explaining what it matches:
javascript// Match a valid US phone number: (XXX) XXX-XXXX or XXX-XXX-XXXX
const phoneRegex = /^\(?(\d{3})\)?[-.\s]?(\d{3})[-.\s]?(\d{4})$/;
// Match ISO 8601 date format: YYYY-MM-DD
const dateRegex = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/;
// Match hex color: #RGB or #RRGGBB (case-insensitive)
const hexColorRegex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;Rule 5: Document Function Contracts with JSDoc
Every function that is exported, shared between modules, or has non-obvious behavior should have a JSDoc comment:
javascript/**
* Retry a failed async operation with exponential backoff.
*
* @param {Function} operation - Async function to execute
* @param {Object} options - Configuration options
* @param {number} [options.maxRetries=3] - Maximum retry attempts
* @param {number} [options.baseDelay=1000] - Base delay in ms (doubled each retry)
* @param {Function} [options.shouldRetry] - Predicate to decide if error is retryable
* @returns {Promise<*>} The resolved value of the operation
* @throws {Error} The last error if all retries are exhausted
*
* @example
* const data = await retryWithBackoff(
* () => fetch("/api/data").then(r => r.json()),
* { maxRetries: 5, baseDelay: 500 }
* );
*/
async function retryWithBackoff(operation, options = {}) {
const { maxRetries = 3, baseDelay = 1000, shouldRetry = () => true } = options;
let lastError;
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
return await operation();
} catch (error) {
lastError = error;
if (attempt === maxRetries || !shouldRetry(error)) throw error;
await new Promise(r => setTimeout(r, baseDelay * 2 ** attempt));
}
}
throw lastError;
}When to Use JSDoc vs. TypeScript
| Scenario | Recommended Approach |
|---|---|
| JavaScript project, no TypeScript | JSDoc for type hints and documentation |
| TypeScript project | Types in code, JSDoc only for descriptions and examples |
| Library or SDK | JSDoc with @example tags for every public method |
| Internal utility function | Brief JSDoc with @param and @returns |
| Private helper (used in one file) | Optional; inline comment if complex |
Rule 6: Use TODO, FIXME, and HACK Consistently
These annotations are searchable across your codebase and help teams track technical debt:
javascript// TODO(alice): Replace with Redis cache after infrastructure migration (Q2 2026)
const cache = new Map();
// FIXME: Race condition when two users submit simultaneously.
// The second submission overwrites the first without conflict detection.
async function submitForm(data) {
await database.save(data);
}
// HACK: Safari 17.2 does not fire the 'resize' event when the
// virtual keyboard opens. Polling as a workaround until Safari 18.
setInterval(checkViewportSize, 500);TODOs Need Deadlines
A TODO without a deadline or owner is a wish, not a task. Always include who is responsible and when it should be addressed. If a TODO has been in the codebase for more than one sprint, either do it or move it to your issue tracker and delete the comment.
Convention for Annotation Format
javascript// TODO(owner): Description (deadline or ticket reference)
// FIXME(owner): Description (ticket reference)
// HACK: Description (when this can be removed)
// Examples:
// TODO(sarah): Add rate limiting to this endpoint (JIRA-1234)
// FIXME(team): Memory leak in WebSocket handler (before v2.0 release)
// HACK: Remove after Chrome 120+ reaches 95% market shareRule 7: Warn About Side Effects and Gotchas
When code has non-obvious side effects, mutations, or constraints, a warning comment prevents future bugs:
javascript// WARNING: This function mutates the input array in-place.
// Pass a copy if you need the original: sortUsers([...users])
function sortUsers(users) {
return users.sort((a, b) => a.name.localeCompare(b.name));
}
// NOTE: This fetch call has no timeout. If the server hangs,
// this Promise will never resolve. Use with AbortController in production.
const response = await fetch(url);
// IMPORTANT: Order matters. Authentication middleware must run
// before authorization. Reversing these causes a 500 error because
// the auth check reads req.user, which auth middleware sets.
app.use(authenticate);
app.use(authorize);Rule 8: Section Dividers for Long Files
In files with many related functions, section comments help readers navigate:
javascript// ============================================================
// User Authentication
// ============================================================
function login(credentials) { /* ... */ }
function logout(sessionId) { /* ... */ }
function refreshToken(token) { /* ... */ }
// ============================================================
// User Profile Management
// ============================================================
function getProfile(userId) { /* ... */ }
function updateProfile(userId, data) { /* ... */ }
function deleteAccount(userId) { /* ... */ }
// ============================================================
// Permission Checks
// ============================================================
function canEdit(user, resource) { /* ... */ }
function canDelete(user, resource) { /* ... */ }However, if your file needs many section dividers, it is probably too long. Consider splitting it into separate modules.
What NOT to Comment
Obvious Code
javascript// BAD: every line is commented
// Declare the variable
let count = 0;
// Increment count by one
count++;
// Check if count is greater than 10
if (count > 10) {
// Log the count
console.log(count);
}
// GOOD: no comments needed, code speaks for itself
let count = 0;
count++;
if (count > 10) {
console.log(count);
}Journal Comments
javascript// BAD: changelog in comments (use Git for this)
// 2026-01-15 alice: Added validation for email field
// 2026-01-20 bob: Fixed bug with empty input handling
// 2026-02-01 alice: Refactored to use async/await
function processForm(data) { /* ... */ }
// GOOD: Git log tells you all of this with author, date, and diffClosing Brace Comments
javascript// BAD: comments on closing braces
if (isValid) {
for (const item of items) {
if (item.active) {
processItem(item);
} // end if active
} // end for
} // end if valid
// GOOD: if your nesting is so deep you need these, refactor instead
function processActiveItems(items) {
const activeItems = items.filter(item => item.active);
activeItems.forEach(processItem);
}Comment Anti-Patterns to Avoid
| Anti-Pattern | Problem | Better Approach |
|---|---|---|
| Commented-out code | Creates confusion about what is active | Delete it; use Git history |
| "// Don't touch this" | Prevents maintenance from fear | Explain WHY it is fragile |
| "// This is a temporary fix" | "Temporary" = permanent | Add a TODO with deadline |
| ASCII art dividers | Visual noise, no information | Simple section headers |
| Apologetic comments | "// Sorry, this is ugly" | Refactor it instead |
| Redundant type comments | "// string" next to a string variable | Use TypeScript or JSDoc types |
Best Practices
Professional Commenting Standards
These practices reflect what teams at engineering-driven companies actually enforce in code reviews.
Treat comments as part of your code. When you change a function's behavior, update its comments in the same commit. Outdated comments are actively harmful because readers trust them and make wrong assumptions.
Write comments for the reader who does not have your context. A new team member joining six months from now should understand your code without asking you. Comments should bridge the gap between what the code does and why it exists.
Use a consistent commenting style across the project. Document your team's conventions in the project's contributing guide: when to use JSDoc, what annotations to use (TODO, FIXME, HACK), and whether to prefer single-line or multi-line comments for different situations.
Run comment quality checks. Tools like ESLint can enforce comment conventions. Pairing a linter with JavaScript debugging techniques gives you a solid workflow for catching issues early. The valid-jsdoc and require-jsdoc rules ensure exported functions have documentation. Custom rules can flag TODO comments older than a configurable age.
Review comments during code review. When reviewing a pull request, read the comments as carefully as the code. Flag comments that restate the obvious, contain outdated information, or are missing where business logic needs explanation.
Common Mistakes and How to Avoid Them
Watch Out for These Pitfalls
These commenting anti-patterns show up in code reviews constantly and drag down codebase quality over time.
Commenting everything. Over-commented code is just as bad as under-commented code. Rely on console methods for runtime diagnostics instead of cluttering your source with obvious play-by-play comments. If every line has a comment, the real information gets buried in noise. Comment selectively: business rules, workarounds, constraints, and non-obvious decisions.
Leaving dead code in comments. Commented-out code blocks create ambiguity: Is this code still relevant? Should it be restored? Was it left by accident? Delete it and rely on version control to preserve history.
Writing comments after the fact as a chore. Comments written as an afterthought tend to restate the code because the developer has already moved on mentally. Write comments as you code, when the reasoning is fresh in your mind.
Using comments to paper over bad code. If your code needs a paragraph of explanation to be understood, the code itself might need refactoring. Comments should supplement clear code, not compensate for confusing code. Understanding strict mode can also help eliminate confusing silent failures that developers might otherwise try to document with warning comments.
Inconsistent annotation usage. Using TODO in some files and FIXME in others for the same kind of issue makes searching unreliable. Define your team's annotation vocabulary and stick to it.
Next Steps
Audit your current project's comments
Go through 5 files in your project and categorize every comment as "useful" or "noise." Delete the noise, improve the useful ones, and add comments where business logic lacks explanation.
Set up ESLint commenting rules
Configure require-jsdoc for exported functions and no-warning-comments to flag TODOs and FIXMEs during CI builds. This creates accountability for resolving technical debt.
Write a team commenting guide
Create a short document (one page) that defines your team's commenting conventions. Include when to use JSDoc, which annotations are standard, and examples of good vs. bad comments.
Practice by documenting an open-source function
Find an undocumented utility function in a popular open-source project and write a JSDoc comment for it. This exercise trains you to understand code deeply enough to explain it to others.
Rune AI
Key Insights
- Comment the "why": explain business rules, constraints, and decisions that code cannot express
- Self-documenting first: use clear naming and function extraction before reaching for comments
- JSDoc for contracts: document parameters, returns, and side effects of every exported function
- Accountable TODOs: every TODO needs an owner, deadline, or ticket reference
- Delete dead code: use Git history instead of commenting out code; dead comments create confusion
Frequently Asked Questions
How many comments should a JavaScript file have?
Should I comment every function in JavaScript?
Is it bad to use TODO comments?
Do comments slow down JavaScript execution?
Should I use single-line or multi-line comments?
Conclusion
Professional JavaScript commenting focuses on explaining why decisions were made, not restating what the code does. The most effective patterns include documenting business rules, warning about side effects, using JSDoc for function contracts, and keeping TODO annotations accountable with owners and deadlines. Treat comments as maintainable artifacts that get updated alongside the code they describe, and delete any comment that adds confusion rather than clarity.
More in this topic
OffscreenCanvas API in JS for UI Performance
Master the OffscreenCanvas API to offload rendering from the main thread. Covers worker-based 2D and WebGL rendering, animation loops inside workers, bitmap transfer, double buffering, chart rendering pipelines, image processing, and performance measurement strategies.
Advanced Web Workers for High Performance JS
Master Web Workers for truly parallel JavaScript execution. Covers dedicated and shared workers, structured cloning, transferable objects, SharedArrayBuffer with Atomics, worker pools, task scheduling, Comlink RPC patterns, module workers, and performance profiling strategies.
JavaScript Macros and Abstract Code Generation
Master JavaScript code generation techniques for compile-time and runtime metaprogramming. Covers AST manipulation, Babel plugin authorship, tagged template literals as macros, code generation pipelines, source-to-source transformation, compile-time evaluation, and safe eval alternatives.