oncokb-code-comments-standards

Write comments that explain why the code exists, key invariants, assumptions, and non-obvious control flow rather than restating syntax. For non-trivial logic, include references to tickets, design docs, or meeting notes so readers can find supporting context.

Comments should cover design intent, preconditions, side effects, limitations, and edge-case behavior that a maintainer needs before making safe changes. Judge obviousness from a first-time reader's viewpoint, not the original author's.

Comments are required on business logic beyond basic CRUD, on fields and data types exposed via API calls, and on fields used in server-side rendering templates. Non-trivial logic should also reference supporting context like tickets or design documents.

Avoid comments that restate code line-by-line, repeat names or syntax already visible, or make vague statements that add no understanding. Prefer improving the code itself when possible and use comments only to close the remaining gap.

Treat reviewer confusion as valid signal rather than arguing from author intent. Resolve it by clarifying with better comments, improving the code itself, or both, so a first-time reader can understand the design.