Vibe Coding Methodology · Lesson 4

Three Comment Elements and Code Protection

AI-generated comments mostly just restate what the code does. Come back three months later, and you can't remember why it was implemented that way. This lesson provides a structure for comments and establishes rules for "deleting code". The page includes two interactive demos.

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 comments" is a phrase AI cannot execute on; you need to provide a fixed structure and examples.

Three-Element Structure

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.

Interactive Demo 1 · Same Function, Two Comment Styles

Click to switch between two comment styles for the same merge_chat_history function, and compare the amount of information each preserves.

chat/history.py
          ContextDesign IntentKey Constraints
        
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    Merges two chat history lists and returns the merged result.
    """
    ...
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    Context: The frontend sends locally cached history on every session restore,
    but the server also maintains a persisted copy — these can diverge after network interruptions.
    Design Intent: Treat the server record as authoritative; only append messages
    unique to the local copy. Avoid a full replacement to prevent overwriting AI reply metadata already on the server.
    Constraint: Any message in `incoming` with role=system is unconditionally discarded and not merged into the result.
    """
    ...

This comment restates the function name — you get the same information with a quick glance at the code. Three months later, when you wonder "why is the server authoritative?" or "why are system messages dropped?", there are zero clues.

Interactive Demo 2 · To Delete or Not — You Decide

Three real-world scenarios — judge what AI should do. Click an option for instant feedback with the relevant rule reference.

Scenario 1 · During a refactor, AI finds a block of code that handles a legacy data format. It thinks it "looks unused" and wants to delete it in passing.

Scenario 2 · After a refactor, the implementation has changed. The existing "Design Intent" comment no longer matches the code.

Scenario 3 · AI thinks fetch is lighter than axios and wants to swap out axios for fetch in the project, modifying package.json while at it.

Correct so far: 0 / 3

Two Protection Rules

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.

Companion Rule · Error Handling

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.

Key Takeaways

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.

Source: This lesson's content is adapted from Chapter 7 "Code Organization and Standards" in itshen/xs_vibe_rules (rule-opensource.mdc).

Three Comment Elements and Code Protection

Context

Design Intent

Key Constraints

Functional Restatement Comment

Three-Element Comment

Comment Protection

Code Deletion Declaration