Three Comment Elements & Code Protection
Background, design intent, key constraints — all three required; no silent deletion of code or dependencies
THE QUESTION THIS PAGE ANSWERS
ANSWER FIRSTWhat is the key idea behind “Three Comment Elements & Code Protection”?
Background, design intent, key constraints — all three required; no silent deletion of code or dependencies
Turn taste into a behavior the product can repeat. The useful outcome is not a nice opinion. It is a visible rule, a small example, and a way to tell when the experience falls below the bar.
Capture one before-and-after example that shows the quality bar without extra explanation.
Polish that improves the surface while leaving the user's uncertainty untouched.
Code can only express "what was done." Why it exists, why it was implemented this way, what to be aware of when calling it — this information can only persist across time if written in comments. "Write good comments" is a phrase AI cannot execute on; you need to provide a fixed structure and examples.
Context
What business problem this function solves and in what scenario it is called. Without context, the reader can only see the implementation, not why it exists.
Design Intent
Why it was implemented this way, the reasons for choosing this approach, and which alternatives were abandoned. This can't be found in git log; comments are the only carrier.
Key Constraints
What callers need to know: side effects, dependencies, edge conditions, and other non-obvious caveats. Without this, the next caller will step on a landmine.
Click to switch between two comment styles for the same merge_chat_history function, and compare the amount of information each preserves.
Three real-world scenarios — judge what AI should do. Click an option for instant feedback with the relevant rule reference.
Correct so far: 0 / 3
Comment Protection
During refactoring, it is prohibited to delete context and design intent comments on the grounds of "the comment is too long," "the code is self-explanatory," or "cleaning up in passing." If an implementation change makes a comment inaccurate, the comment must be updated in sync. The only test: could someone taking over the code understand why it was done this way without this comment?
Code Deletion Declaration
Before deleting any existing functional code, you must explicitly inform the user with a reason. Silent deletion on grounds of "cleaning up in passing" or "looks unused" is prohibited. When you believe a code block should be removed, first annotate it with // TODO: Suggested removal - Reason: xxx and delete only after receiving approval.
No empty catch blocks. All try/catch blocks and error branches must have substantive handling: logging + a user-visible error message, or a reasonable fallback. A bare console.log(e), pass, or // ignore all constitute silent error swallowing and are never permitted.
The mission of comments is to preserve decision-making information that code cannot express. The three-element structure gives AI a format it can follow; the protection rules prevent it from deleting them. Together, they let knowledge persist across time.
Turn the feeling in “What's the problem” into a judgment
“Code can only express "what was done." Why it exists, why it was implemented this way, what to be aware of when calling it — this information can only persist across time if writte…” points out that AI has lowered the bar for making something usable. The skill readers need is noticing what is wrong and turning that feeling into an actionable requirement.
Watch the user's next action, not just the surface
Turn “What business problem this function solves and in what scenario it is called.” into observable questions: does the user know what happened, what to do next, and how to recover from an empty or failed state? Does the hierarchy make the important information visible first?
Pretty is not the same as usable
Apply “The mission of comments is to preserve decision-making information that code cannot express.” to a second screen or flow. Record one moment of hesitation and the user action after the change; observable behavior is stronger evidence than polish alone.
From “What's the problem” to “Context”
“What's the problem” grounds the problem in “Code can only express "what was done." Why it exists, why it was implemented this way, what to be aware of when calling it — this information can only persist across time if written in comments. "Write good com…”. “Context” then moves it toward “What business problem this function solves and in what scenario it is called. Without context, the reader can only see the implementation, not why it exists”. Together, they show that the lesson is not just a conclusion to remember, but a claim with conditions.
Carry the judgment into the next situation
For experience work, turn abstract impressions into user actions: did the person understand the state, find the next step, recover from an error, and want to continue?
- “What's the problem”: Code can only express "what was done." Why it exists, why it was implemented this way, what to be aware of when calling it — this information can only persist across time if written in comments. "Write good com…
- “Context”: What business problem this function solves and in what scenario it is called. Without context, the reader can only see the implementation, not why it exists
- “The closing point”: Three real-world scenarios — judge what AI should do. Click an option for instant feedback with the relevant rule reference
The final “The closing point” brings the discussion to “Three real-world scenarios — judge what AI should do. Click an option for instant feedback with the relevant rule reference”. The useful thing to carry forward is knowing which judgments must be revisited when input, scale, or risk changes.
I turned one judgment from this article into a small experiment I could run today. Knowing what to observe next is more useful than simply remembering the conclusion.
After reading this, I first looked for the conditions behind the idea instead of copying the method into a project. That order made the later trade-offs much clearer.
When this judgment reaches real work, which constraint should be added first? I am curious which step matters most between reading and the first practical attempt.
No discussion on this article yet.