Practice self-documenting code vocabulary: naming for clarity, explaining the WHY in comments, extracting meaningful functions, and reducing comment noise.
0 / 5 completed
1 / 5
A code reviewer says 'The code should explain the WHAT; the comment explains the WHY.' What does this principle mean?
Self-documenting code uses clear naming so readers can understand what it does without comments. Comments are most valuable when they explain why a decision was made — business rules, historical constraints, or non-obvious trade-offs that the code itself cannot communicate.
2 / 5
Your code review says 'Rename for clarity instead of commenting.' Which example demonstrates this principle?
Instead of writing `if (x) { // check if user is authorized }`, rename the variable: `if (isUserAuthorized)`. The code now reads clearly without needing a comment — the name carries the meaning.
3 / 5
A comment review says 'The variable name maxRetryAttempts needs no comment.' Why?
Self-documenting variable names like `maxRetryAttempts` communicate their type (a count), scope (maximum), and purpose (retry attempts) without any comment. Adding a comment like '// the maximum number of retry attempts' would be noise — it repeats the name in prose.
4 / 5
Your team's coding standard says 'Extract meaningful functions instead of commenting blocks.' What is the benefit of this approach?
When you extract a block of code into a named function like `validateEmailFormat()`, the name itself documents what the block does — and the function is reusable. Comments above blocks can go stale (code changes but comments don't), while function names are enforced by usage.
5 / 5
A mentor says 'This comment is a code smell.' The comment reads: `i++; // increment i`. Why is this comment a problem?
Comments that restate the obvious ('// increment i') are noise — they add length without adding understanding. If a reader can't understand `i++`, the problem is naming, not missing comments. This type of comment is a code smell indicating the code may lack clarity elsewhere.