Historical Context & Motivation
Since the earliest days of programming, developers have recognized that source code is read far more often than it is written. When you write a program, you might spend a few hours crafting a function, but your teammates — or even future-you — might read that function dozens of times over the life of a project. Code comments evolved as a way to embed human-readable explanations directly inside the source code, bridging the gap between what a machine executes and what a person needs to understand.
Despite all of these advances, most beginner programmers still struggle with what to comment. They either write too many obvious comments that just restate the code, or they write none at all and leave future readers guessing. The central question this lesson addresses is: How do you write comments that genuinely help someone understand your code? The answer lies in explaining intent (why you did something) and assumptions (what conditions must be true for this code to work correctly).
Core Principles of Effective Comments
Writing useful comments is a skill, not a chore. Great comments don't repeat the code — they add context that the code alone cannot convey. Think of comments as a conversation with the next person who reads your code, which might very well be yourself six months from now. The following principles form the foundation of comment-writing craft.
Explain WHY, Not WHAT
State Your Assumptions
Keep Comments Up-to-Date
Prefer Clear Code Over Comments
Use the Right Format
Visual Explanation — Good vs. Bad Comments
The diagram below compares two approaches to commenting the same piece of code. On the left, you see comments that merely restate what the code does — these add visual clutter without adding understanding. On the right, the comments explain intent and assumptions, giving the reader genuine insight into the developer's reasoning.
Notice the pattern: in the good examples, the variable name maxRetries already tells you what the value represents. The comment adds why it is set to 10 specifically and where that number came from. This is the essence of intent-driven commenting: the code handles the 'what,' and the comment handles the 'why.'
How Intent & Assumption Comments Work
Understanding the mechanics behind effective commenting starts with recognizing the two fundamental types of hidden knowledge in any codebase: intent and assumptions. Intent is the purpose behind a decision — the business requirement, the algorithm choice, or the design trade-off. Assumptions are the conditions that must hold true for the code to work correctly, even though they aren't enforced by the code itself.
JavaScript Comment Syntax
JavaScript provides three standard comment formats. Single-line comments use // and extend to the end of the line. They are ideal for brief notes about a single statement. Multi-line comments use /* */ and can span multiple lines, making them suitable for longer explanations at the top of a function or file. JSDoc comments use /** */ and follow a structured format with tags like @param and @returns; tools can parse them to auto-generate documentation.
The Intent–Assumption Framework
When you sit down to comment a piece of code, run through two mental questions. First: "Why did I write this particular line or block this way?" If the answer isn't obvious from the code, write an intent comment. Second: "What must be true about the data, the environment, or the caller for this to work?" If there's a hidden dependency, write an assumption comment. These two questions cover the vast majority of situations where comments genuinely help.
Classifying Comment Types in JavaScript
Not all comments serve the same purpose. Professional developers generally classify comments into several categories, and understanding these categories helps you decide which to use. The table below breaks down the most common types you'll encounter in JavaScript projects, with a focus on which ones genuinely add value.
| Comment Type | Purpose | Example | Value Level |
|---|---|---|---|
| Intent | Explains why a specific approach was chosen | // Debounce to avoid flooding the API on each keystroke | ★★★ High |
| Assumption | States a condition the code depends on but doesn't enforce | // Assumes price is in USD cents, not dollars | ★★★ High |
| TODO / FIXME | Marks known issues or planned improvements | // TODO: Add input validation for negative values | ★★ Medium |
| Warning | Alerts about non-obvious consequences | // WARNING: Mutates the original array in place | ★★ Medium |
| JSDoc | Formal documentation for functions, classes, and modules | /** @param {string} name - User's display name */ | ★★★ High |
| Narration | Restates what the code already says | // increment i by 1 | ★ Low / Avoid |
As you can see, intent comments and assumption comments are the most valuable because they capture knowledge that would otherwise exist only inside the original developer's head. Narration comments — the kind that say 'increment i' next to i++ — actively harm readability by adding noise without adding meaning. Your goal as a developing programmer should be to maximize high-value comments and eliminate narration.
Worked Example — Commenting a Real Function
Let's walk through a complete example. Imagine you're building a web app for a school cafeteria, and you need a function that calculates the discounted price for students who qualify for free or reduced-price lunch. We'll start with uncommented code and progressively add intent and assumption comments.
function calcLunchPrice(basePrice, studentId, discountTier) {
if (discountTier === 'free') return 0;
if (discountTier === 'reduced') return basePrice * 0.4;
if (basePrice > 5.00) return basePrice - 0.50;
return basePrice;
}
A reader can see WHAT the function does — it returns different prices based on a discount tier. But several questions remain unanswered.basePrice is a positive number in dollars (not cents). It assumes discountTier is one of exactly three values: 'free', 'reduced', or undefined/other. It also assumes the student's eligibility was already verified before this function was called./**
* Calculates the lunch price after applying discount tiers.
* Assumes `basePrice` is in US dollars (not cents) and is > 0.
* Assumes `discountTier` is validated upstream by verifyEligibility().
* @param {number} basePrice - Menu price before discounts
* @param {string} studentId - Used for audit logging (not pricing)
* @param {string} discountTier - 'free', 'reduced', or undefined
* @returns {number} Final price the student pays
*/
function calcLunchPrice(basePrice, studentId, discountTier) {
// NSLP 'free' tier: student pays nothing
if (discountTier === 'free') return 0;
// NSLP 'reduced' tier: student pays 40% per federal guidelines
if (discountTier === 'reduced') return basePrice * 0.4;
// Cafeteria incentive: $0.50 off meals over $5 to encourage
// choosing the premium healthy option (Policy #12, Sept 2024)
if (basePrice > 5.00) return basePrice - 0.50;
return basePrice;
}Strengths, Pitfalls, and Best Practices
Like any tool, comments can be used well or poorly. The difference between a helpful codebase and a frustrating one often comes down to comment quality. Understanding both the strengths and the common pitfalls of commenting will help you develop a balanced approach.
| Strengths | Pitfalls |
|---|---|
| Intent comments make code maintainable — future developers can modify logic without breaking hidden expectations. | Stale comments that contradict the current code are worse than no comments, because they actively mislead readers. |
| Assumption comments prevent bugs by making invisible dependencies visible before they cause failures. | Over-commenting every line creates visual noise and makes it harder to scan the actual logic. |
| JSDoc comments integrate with IDEs, enabling auto-complete tooltips and generated documentation. | Using comments to explain bad code instead of fixing it ('comment crutch') hides deeper design problems. |
| TODO/FIXME markers help teams track technical debt and planned improvements in a discoverable way. | Leaving commented-out code blocks in production clutters the file — use version control (Git) instead. |
Connecting to Professional Practices
The commenting skills you've learned in this lesson form the foundation for professional software communication practices that you'll encounter as you advance. In real-world teams, comments are just one part of a broader documentation ecosystem that includes code reviews, commit messages, pull request descriptions, and technical design documents. The intent-and-assumption mindset applies to all of these formats.
| This Lesson (Basics) | Professional Level |
|---|---|
| Single-line // comments for intent | ADRs (Architecture Decision Records) that formally document design choices and their trade-offs |
| Assumption comments in code | Contract-based programming with runtime assertions and TypeScript types that enforce assumptions |
| JSDoc for function documentation | Auto-generated API documentation sites using tools like Storybook, Swagger, or TypeDoc |
| TODO markers for known issues | Issue trackers (GitHub Issues, Jira) with linked commits so every change traces back to a requirement |
As you move into AP Computer Science, college courses, or internships, you'll find that teams value developers who communicate clearly in code just as much as those who write clever algorithms. The two-question framework — "Why did I do this?" and "What must be true?" — will serve you well in every one of those contexts, whether you're writing a comment, a commit message, or a design document.
Practice Problems
// add 1 to counter above the line counter += 1; is considered a poor comment. What kind of comment would be more useful here?function getShippingCost(weight) {
if (weight <= 0) return 0;
return weight * 2.5 + 3.99;
}
What intent and assumption would you document?// check if score is more than 89
function isHonorRoll(score) {
return score > 89;
}enemies is an empty array. Add comments that would have helped your teammate catch this bug before it shipped.
function getStrongestEnemy(enemies) {
let strongest = enemies[0];
for (let i = 1; i < enemies.length; i++) {
if (enemies[i].hp > strongest.hp) {
strongest = enemies[i];
}
}
return strongest;
}Lesson Summary
Effective code comments serve as a bridge between the developer's mind and the reader's understanding. The core skill is learning to explain intent — the why behind a decision, such as a business rule, an algorithm choice, or a performance trade-off — and assumptions — the invisible conditions that must hold true, like input formats, sort orders, or pre-validated data. JavaScript provides single-line comments (//) for brief inline notes, multi-line comments (/* */) for longer explanations, and JSDoc (/** */) for structured documentation that tools can parse automatically.
Remember the two-question framework: before commenting any code, ask "Why did I write it this way?" and "What must be true for this to work?" Avoid narration comments that restate the obvious, and always keep comments up-to-date when code changes. Prefer clear code first and then supplement with comments where the code alone cannot tell the full story. These habits form the foundation of professional software communication and will serve you well from your first group project through your career.