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 Resources
Related Cheatsheets
- JavaScript Cheatsheet
Reference for comment syntax, JSDoc tags, and formatting conventions.
Practice Comments and Readability
3 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.