Questions: Code Comments and Style

Question 1

A developer writes: `total = price * quantity # multiply price by quantity`. A reviewer flags this comment. Why?

• A. The comment is in the wrong location — it should be above the line, not inline
• B. The comment restates what the code already shows and adds no useful information
• C. Multiplication should not be commented because it is a built-in operation
• D. The variable names are unclear and should be fixed before any comment is added

Answer: (B)

The comment 'multiply price by quantity' exactly restates what `price * quantity` already communicates to any reader who knows the language. Good comments explain WHY the code does what it does — the intent, the constraint, the non-obvious choice — not WHAT the code does, which the code itself shows. This comment adds visual noise without adding knowledge. A useful comment here might explain why this specific formula is used (e.g., '# before tax; tax applied separately in checkout module').

Question 2

A programmer has a complex 20-line block that computes a priority score. They are about to write a long comment explaining the formula. What should they consider first?

• A. Whether the comment should be in the function header instead of inline
• B. Whether refactoring the code into a well-named function would eliminate the need for the comment
• C. Whether the programming language supports multi-line comment syntax
• D. Whether the formula has already been documented in external specifications

Answer: (B)

When a comment needs to be long to explain complex logic, that is often a signal that the code can be refactored to be more self-explanatory. A function named `calculate_priority_score(urgency, recency, user_tier)` communicates intent without any comment. The block inside may still benefit from a brief comment explaining the business rule it encodes, but the primary question should always be: 'Can I make the code clearer so less explanation is needed?' Refactoring to reduce comment burden produces more maintainable code than extensive commenting of hard-to-follow code.

Question 3

Using consistent indentation and naming conventions matters more for long-term maintainability than which specific convention is chosen.

• T. True
• F. False

Answer: True

The specific convention — 2 vs 4 spaces, camelCase vs snake_case — matters far less than applying any convention consistently throughout a codebase. Mixed conventions force readers to spend mental energy parsing formatting instead of logic. Most languages have community standards (Python's PEP 8, JavaScript's various style guides) that reduce decision fatigue, but the fundamental principle is consistency within a project. A team that uses a non-standard but consistent style will outperform a team that uses the 'correct' style inconsistently.

Question 4

Code that is well-named and clearly structured still requires comments on most lines to be considered professional quality.

• T. True
• F. False

Answer: False

This inverts the principle. Well-named, clearly structured code requires *fewer* comments, not more. The goal is self-documenting code: variable and function names that express intent, logical structure that reveals flow, and comments only where the code cannot speak for itself — edge cases, non-obvious choices, constraints from external systems. Adding comments to every line of readable code makes the code harder to scan by increasing visual noise. Professional-quality code uses comments surgically, not pervasively.

Question 5

Why should comments explain 'why' rather than 'what,' and what kinds of 'why' are most valuable to document?

Model answer: The 'what' is already visible in the code — any reader who knows the language can see what operations are performed. The 'why' is what the code cannot show: the business rule being enforced, the bug being worked around, the alternative approach considered and rejected, the external constraint that forced an unusual choice. The most valuable 'why' comments include: explaining a non-obvious algorithm choice ('using binary search here because this list is always pre-sorted'), documenting a workaround ('off-by-one added to compensate for the API's 1-indexed responses'), and warning about fragile dependencies ('this order matters — module X must be initialized before Y').

Comments that restate what the code does become liabilities: they can go stale when the code changes but the comment is not updated, creating misleading documentation. Comments that explain why rarely go stale — the business rule or constraint usually persists even when the implementation changes. Separating 'what' (code's job) from 'why' (comment's job) produces documentation that remains accurate and useful over time.