Writing Clear and Readable Code
Redundant comments restate what the code already shows; useful comments add context, meaning, or reasoning that the syntax cannot express.
The Reader’s Missing Question
When you return to your own code months later, or when a teammate reads it for the first time, a useful comment can explain the intent in seconds. But a comment is not automatically helpful just because it exists. The important question is whether the comment tells the reader something the code cannot show by itself.
A strong comment answers why the code matters, what an assumption means, or how a value should be understood. It does not merely translate visible syntax into English.
Redundant Versus Useful Comments
A redundant comment restates information already present and clear in the code. For example, a comment saying that 5 is being assigned to v does not tell the reader anything beyond what the assignment already shows. It takes up space and requires maintenance without adding insight.
A useful comment adds information that is not explicit in the syntax. If the comment explains that v represents velocity measured in meters per second, it gives the number a real-world meaning. The code shows the assignment; the comment explains how the value should be understood and used.
Classifying a comment
A line assigns 5 to v. One comment says 'Assign 5 to v'. Another says that v is velocity measured in meters per second. Which comment adds more value?
Read the code: The assignment already makes the value 5 and the target name v visible.
Test the first comment: The phrase 'Assign 5 to v' only translates the assignment into English, so it is redundant.
Test the second comment: The velocity meaning and the measurement unit are not expressed by the assignment itself, so this comment adds domain context.
The comment about velocity and meters per second is useful because it explains meaning that the syntax cannot express.
Three Sources of Useful Context
Useful comments commonly explain intent, assumptions, domain-specific meaning, units, or the reason a particular approach was chosen. They may also point readers toward external documentation. These details answer questions that syntax alone cannot answer.
- Intent: why this approach is being used.
- Assumptions: what must be true for the code to work.
- Domain meaning: what a value represents in the problem being solved.
- Units: how a number should be interpreted, such as meters per second.
- External reasoning: why a particular design choice was made or where related documentation can be found.
Names, Expressions, and Comment Choice
Descriptive variable names can make comments unnecessary because the name itself communicates meaning. However, names that are very long can make a complex expression difficult to read. Readability is therefore a balance: the clearest choice is not always the longest possible name.
Balancing names and context
A calculation combines several values, but every variable name is more than 20 characters long. Should the code always use the longest descriptive names?
Check visual clarity: If long names turn the calculation into a wall of text, the reader may struggle to follow the arithmetic.
Consider concise names: Shorter names can make the expression easier to parse at a glance.
Add missing context: A clear comment can explain what the calculation represents or state an assumption, such as the tax-rate assumption mentioned in the source material.
Review the result: The goal is not maximum name length or maximum comment count. The goal is an expression that is easy to read and has the context needed for correct maintenance.
Use names that communicate meaning without making the expression needlessly dense, then add a comment when intent or an assumption remains unclear.
| Situation | Better choice | Reason |
|---|---|---|
| The name already makes the meaning clear | Avoid a comment that repeats the name | The code already communicates the relevant information |
| The value has domain meaning or units not visible in syntax | Add a context comment | The comment explains information the code cannot show |
| Very long names make a calculation hard to parse | Use concise names and add focused context if needed | Expression readability and domain clarity both matter |
| A design choice or assumption is not obvious | Explain the intent or assumption | The reader needs reasoning, not a syntax translation |
Use comments to supply missing meaning, not to narrate visible operations.
Comments Must Age with Code
A comment is part of the code's explanation, so it must remain synchronized with the code. An outdated comment is worse than no comment because it actively misleads readers. When a variable, calculation, assumption, or design choice changes, review the comment that describes it.
Translating syntax into English
The assignment already shows that operation, so the comment adds no insight.
Fix:
Explain what v means in the problem domain, such as velocity measured in meters per second.Assuming every useful comment should describe what the code does
The code already shows the operations; the missing information is more likely to be intent, an assumption, or domain meaning.
Fix:
Comment on why the approach is used or what assumption the calculation depends on.Using extremely long variable names everywhere
Descriptive names can improve meaning, but excessive length can make expressions visually dense.
Fix:
Balance concise names with a focused comment when context still needs explanation.Leaving comments unchanged after code changes
Readers may trust the comment and be misled.
Fix:
Review and synchronize comments whenever the related code changes.
Practice the Comment Test
For each proposed comment, decide whether it is redundant or useful. If it is redundant, rewrite its purpose as a question the reader might actually need answered. If it is useful, identify whether it explains intent, an assumption, domain meaning, units, or a design reason.
Hints
- Ask whether the code already shows the information in the comment.
- Look for meaning that the syntax cannot express.
- Check whether a clearer but not excessively long name would remove the need for the comment.
- Check whether the comment would still be accurate after a future code change.
What do you think happens?
A variable has a concise name, and a complex expression uses several such variables. What should you check before adding a comment?
Reveal answer
Answer: Whether the expression needs domain context or an assumption
A comment is most valuable when it adds meaning, intent, or reasoning that the syntax and names do not already provide. Very long names can make the expression harder to read, so clarity requires balance.
A Practical Standard
- Remove comments that merely restate visible syntax.
- Use comments to explain intent, assumptions, domain meaning, units, or design reasoning.
- Let descriptive names carry meaning when they remain readable.
- Prefer concise names with focused context over extremely long names that make expressions hard to parse.
- Update comments whenever the code or its assumptions change.
Key Takeaways
- Redundant comments translate code into words without adding information.
- Useful comments explain why the code exists, what assumptions it relies on, or what values mean in the problem domain.
- Descriptive names reduce the need for comments, but names that are too long can damage expression readability.
- A comment should remain synchronized with the code because outdated comments can mislead readers.
- The goal is not to comment everything or nothing; it is to provide context that the code cannot communicate on its own.