commenting-rules.md

Coding Guidelines: Developer-Friendly Commenting

Use these rules when the user requests documentation or comments for a file.

CRITICAL: ZERO-SIDE-EFFECT POLICY

Your ONLY task is to add comments. You are strictly forbidden from changing the code implementation.

1. The "Do No Harm" Rule

• Safety First: If adding a comment to a complex line (like nested ternaries) risks breaking syntax, SKIP THE COMMENT.
• Preservation: You must preserve the code structure exactly.
  • Do NOT fix bugs.
  • Do NOT reformat lines (Prettier/ESLint).
  • Do NOT change variable names.

---

HIGHEST PRIORITY: Post-Ternary-Colon Comment Trap

DO NOT place JSX comments immediately after ternary : operators.

This pattern ALWAYS BREAKS:

) : (
  {/* This breaks - placed right after colon */}
  <Component />
)

The parser expects an expression (like <Component />), not a comment. If you need to comment, use one of these safe alternatives:

1. Comment BEFORE the ternary (preferred)
2. Comment INSIDE a wrapper element (if unavoidable)
3. SKIP the comment (safest if in doubt)

2. Syntax Verification (Anti-Hallucination)

Before outputting code, you must internally verify:

• Brackets: Do all {, (, and [ have matching closing counterparts?
• JSX: Are all <div> and components properly closed?
• Ternaries: Did you accidentally break a ? or : operator?
• Post-Colon Comments: Did you place any {/* */} immediately after a : in a ternary? (INVALID - remove it)
• Comment Context: Is every JSX comment {/* */} inside a JSX element or wrapped in parentheses?

3. Strict Syntax Rules (The "Anti-Break" List)

A. JSX & Return Blocks (CRITICAL)

• Syntax: Inside any return (...) or JSX block, you must ONLY use {/* comment */}.
• Forbidden: NEVER use // inside JSX. It will render as text or break the parser.

B. Ternary Operators (condition ? true : false)

This is the most common cause of errors. Follow this strictly:

• External Comments Only: Do NOT try to insert comments inside the ? or : branches unless they are large blocks.

• CRITICAL: Never place a JSX comment {/* */} immediately after a ternary : operator or right before its expression.

• Best Practice: Place the comment ABOVE the start of the ternary condition.

  • DO:

  {
    /* Show loading state if fetching, otherwise show list */
  }
  {
    isLoading ? <Loading /> : <List />;
  }

  • DON'T (Breaks Code):

  {
    isLoading ? ( // check loading
      <Loading /> // else
    ) : (
      <List />
    );
  }

  • ALSO DON'T (Breaks Code - Post-Colon Comments):

  {
    condition ? (
      <ComponentA />
    ) : (
      {/* This comment breaks syntax - placed right after colon */}
      <ComponentB />
    )
  }

  WHY THIS FAILS: The parser expects an expression after :, not a JSX comment block. The {/* */} is not a valid expression in this context.

  • CORRECT Alternative (Comments Inside Container):

    {
      condition ? (
        <ComponentA />
      ) : (
        <div>
          {/* Safe comment inside JSX element */}
          <ComponentB />
        </div>
      );
    }

4. Context & Parent Components

1. Check Active Chat: Review the current chat history first.
2. File Lookup: Only read the parent component file if the prop context is missing from the chat AND entirely unclear.
3. Goal: Explain where data comes from (e.g., "Passed from DashboardContainer").

5. End-to-End Coverage

Add a specific one-liner comment before every logical block:

• Functions: What it handles.
• State: What data is stored.
• Effects: Trigger and result.
• Logic: &&, ||, and if statements.
• Props: Origin and usage.

6. Exclusion List

• Imports: Do NOT add comments for imports.
• Getters/Setters: Do NOT comment inside simple one-line objects.

7. Examples of Safe Behavior

Safe JSX Commenting: return (

{/* Header Section: Displays title and back button */}

{/* Content Area: Renders list or empty state based on data */}
{hasData ? (
  <List items={items} />
) : (
  <EmptyState />
)}

);

Safe Logic Commenting: // Calculate user permission level based on role and parent props const canEdit = user.role === 'admin' || parentProps.allowEdit;