System Development: Too Few Comments Make Code Hard to Understand, Too Many Are Ignored—How Many Is Enough?

Code comments are not about writing as many as possible, nor about omitting them entirely. There is only one core principle: comments should capture only what the code itself cannot convey—especially decision rationale, business rules, potential risks, and change constraints. To decide whether a comment is worth keeping, ask whether future maintainers might stumble without it. Based on project delivery practices in 2026, most mature teams focus comments on the "why" and the "boundaries" rather than restating the code. If you are struggling with "too few comments to understand, too many comments to read," the screening approach below can be adopted directly as your team guideline.

Three Problems Comments Really Solve

The goal of comments is not to increase the "comment ratio" but to reduce the cognitive load of future code changes. In practice, comments worth writing typically address three issues:

• Intent: Why does this code exist? What business problem does it solve? For example, "Check inventory first and then lock to avoid overselling" adds more explanatory value than "inventory.plus()".
• Constraints: What must not be touched? For instance, "This interface depends on the third-party timeout; do not lower it below 5 seconds" or "This field is compatible with old clients; do not change its length arbitrarily."
• Status: Is this logic temporary, deprecated, or in transition? For example, "Transitional logic; remove it in the next release when the order service goes offline" prevents readers from agonizing over it.

If at least one of these questions yields "useful information," the comment has value; if all three yield "none," the comment is mostly redundant.

The Three-Question Screening Method: Should a Comment Be Written?

It is common to see projects where every function has a comment, yet the truly complex parts have none. We later switched to a "three-question screening method"—before writing a comment, ask yourself:

1. Can the intent of this code be directly inferred from its naming and structure? If a function is named calculateDiscount(), then a comment like "calculate discount" is redundant. If it is named handleData(), a comment explaining "handle inventory rollback after order cancellation" is essential.
2. Are there hidden business rules, compatibility constraints, or performance-sensitive points? For example, "This loop cannot be parallelized because it shares the same order number" or "This field value comes from an old version migration; treat null as 'not set.'" Without such comments, future modifications are likely to cause pitfalls.
3. What piece of information, if missing, would cause rework or incidents during future modifications? This question is especially critical. If the answer is "I won't know whether to deduct inventory or record the transaction first," then the comment must clearly state the order and the reason.

Screening in this order, you should write a comment only when the third question can be answered concretely. Comments written this way are decision points, not background noise.

Comparing Common Comment Types: When to Write, How Much

Comments in different positions serve different purposes. Based on project delivery conventions, they are typically divided as follows:

• File/module header comments: Write only when the module's responsibility is unclear, stating what it does and does not handle. Avoid writing authors and dates; leave those to version control.
• Function/method comments: For public interfaces, clearly document input parameters, return values, exceptions, and contracts; for private functions, write as needed. The typical length is 3–6 lines, enough to convey what, why, and what to watch out for.
• Inline comments: These are easily abused into repetitive noise. Use them only for code ordering, edge conditions, and hidden dependencies. The experience range is no more than 2 per 100 lines; exceeding that suggests naming or structure may be problematic.
• TODO/FIXME comments: Must be tied to a task ticket number; otherwise, they become untrackable "historical debt" after three months. It is also recommended to change date-stamped TODOs to "version + task number."
• DocBlock comments: Aimed at callers, e.g., API parameter descriptions. In 2026, common practice is to manage these with OpenAPI or code generation tools; the handwritten part focuses on decisions like "why not directly call an existing tool."

Compare two extreme approaches: writing no comments at all and relying solely on naming and structure—which suits one-off scripts or pure internal prototypes—versus writing many "decision comments" in critical business code—which suits long-term maintenance and multi-person collaboration. Neither is absolutely right or wrong, but the middle ground is more likely to spiral out of control: either comments become parrot-like repetitions, or the code logic changes while comments still describe the old behavior.

The Cost of Comments and a Counterexample

Comments are not free. Each line must be maintained, and a wrong comment is worse than none. A common scenario in projects: a team, to satisfy a "comment ratio of at least 30%," wrote explanations for every getter and setter, but the truly complex discount calculation logic received only half a line: "// calculate discount." Later, when product strategy changed, the colleague integrating with the code spent an entire afternoon guessing, and only recovered the rule by digging through Git history. That rework cost an extra 3 days. Xiyue Company adjusted its rules in subsequent delivery projects: the comment ratio was no longer a metric; it was replaced by "coverage of key decision comments." In design reviews for new requirements, teams must specify which places need the "why" to be written. During acceptance sampling: if, after deleting a comment, no one on site could articulate the constraints of that code, it was required to be supplemented. After implementing this standard, rework was significantly reduced, and code reviews no longer argued over whether to remove a comment.

Comment Acceptance Criteria: What Counts as Qualified

During code reviews and delivery acceptance, use these five quick checks:

• If any comment line is deleted, can code readers still understand "why it cannot be written the other way around"?
• Do comments only explain reasons, boundaries, and business rules, instead of repeating the code itself?
• Do key flows (state machines, scheduled tasks, async callbacks) all have flowcharts or comment references?
• Are comments kept in sync with code updates? Reject cases where "comments describe old logic while code runs new logic."
• Are there comments written just for the sake of writing, such as "// add 1" or "// loop"? If so, delete them.

These five checks are actionable and not based on subjective feeling. If a team persists for a few rounds, comments will naturally converge to the "decision level" rather than the "description level."

Applicable Scenarios and Boundaries

Suitable for: long-term maintained business systems, public modules collaborated on by multiple people, mid-platform services with frequent handovers, and projects that need to interface with external clients. In these scenarios, comments are part of communication cost and should be spent.

Not suitable or unnecessary: one-off scripts, exploratory prototypes, pure local tools, and temporary logic with fewer than a few hundred lines that will not iterate. For these, spending time adjusting naming and structure is more effective than writing comments. If your team has not even unified naming conventions, do not talk about comment guidelines first—otherwise you are just covering bad code with a blanket.

Furthermore, comments on public interfaces are part of the API contract; missing them affects integration efficiency. But comments on internal implementations can be more restrained. The boundary: Comments should serve "modification safety," not "code aesthetics."

Frequently Asked Questions

What is the difference between comments and docblocks?

Comments are for modifiers; docblocks are for callers. Docblocks for public APIs must be complete, while comments on internal implementations only need to cover the "why."

Should I still write comments if the code is self-explanatory?

If the logic is immediately obvious, don't write one. But "self-explanatory" means a colleague unfamiliar with the business can also understand it, not just you.

Should comments include authors and dates?

Not recommended; Git history is more accurate. Dates and author info can become stale, but "why" does not.

If no one on the team reads comments, should I still write them?

First address the issue of "who maintains the code and how often." If it is truly unmaintained for long periods, don't force it; but once someone steps into a pitfall, turn that lesson into a comment.

Can good naming replace comments?

Most of the "what" can be replaced by naming, but naming cannot express the "why" and "boundaries." Naming addresses the surface; comments address causality.

Action suggestion: Put the "three-question screening method" in the project README or team guidelines and try it for one week in the next iteration. The point is not to eliminate comments or to force writing as many as possible, but to make every comment answer "will you step in a pitfall if this is deleted?" If your project has disorganized naming, start with renaming and splitting functions; comment guidelines can wait. Applicable boundary: long-term maintained code must have decision comments; one-off scripts need none. Don't let comments become a burden, and don't let the code lose its map.