A 20-token comment may be cheaper than paying for one code review and one production rollback. We believe the next barrier in AI programming is not whether models can write code, but whether developers can clearly preserve in code why they wrote it that way.
What this is
Source code usually tells an AI only “what” is done, but rarely explains why an alternative approach cannot be used. Comments and docstrings—text placed alongside code or functions to explain their purpose—carry intent: whether a function has side effects, whether call order is fixed, and which seemingly inefficient implementations must remain untouched.
The article identifies four types of high-value comments: contracts, which specify inputs, return values, and side effects; pitfalls, which flag code that looks optimizable but cannot be changed; invariants, which record constraints that must continue to hold; and trade-offs, which explain why a more complex approach was chosen. The test is straightforward: if omitting the explanation could lead a person or model to make a mistake, it is worth writing; merely restating the code is not.
Compared with documentation in a Wiki or README, inline comments sit closer to the code and are easier for AI systems to read alongside it. The article estimates that three lines of comments may require about 40 tokens, while reviewing a 300-line implementation may consume about 4,000 tokens. However, this is an estimate based on a specific example, not evidence that every project will achieve the same proportional efficiency gain.
Industry view
Our judgment is that this shifts AI programming from “smarter autocompletion” toward “more reliable engineering collaboration.” As code-generation capabilities converge, the real differences between development teams will come down to context quality: teams that consistently provide accurate, maintainable explanations of intent will spend less time fixing code after models make decisions on their own.
The risks are just as clear. First, outdated comments give models an authoritative-seeming answer that is wrong, potentially making them more dangerous than having no comments at all; relying solely on developer diligence cannot guarantee long-term quality. Second, excessive commenting can create a new kind of noise. If teams paste every design document beside a function, models will still be distracted by large volumes of irrelevant information. Third, these gains depend heavily on the codebase, task, and model capabilities. Token savings observed in individual cases should not be treated as universal returns.
The article therefore argues for reviewing comments and code together in the same pull request and checking them with scripts, a more dependable approach than simply telling everyone to write more comments. Static scripts can identify missing explanations, however, but they cannot determine whether those explanations are accurate or current. Code owners must ultimately remain accountable.
Impact on regular people
For enterprise IT: Companies can incorporate critical comments into coding standards and review processes, prioritizing high-risk modules such as payments, permissions, caching, and state machines rather than chasing comment volume.
For individual professionals: Developers using AI programming tools will benefit from clearer task specifications; in team collaboration, articulating boundaries and constraints may save more time than repeatedly refining prompts.
For consumer markets: In the short term, users may not perceive AI programming as becoming “smarter” because of this shift. But as code quality and delivery stability improve, AI-generated features may change in reliability, iteration speed, and user experience.