AI Skill Report Card
Writing Code Comments
Code Comments
Default: no comments. This skill is the decision framework, exceptions, and examples.
Quick Start13 / 15
Before writing a comment, ask in order:
- Is this a public controller endpoint or interface member not self-evident from its signature? → Write
///XML docs (JSDoc for exported JS). - Is this an existing comment your change makes wrong? → Fix or remove it now, in this change.
- Does it explain a non-obvious business rule, regulatory constraint, or workaround — not a restatement of the code? → One brief line, at the point it applies.
- Otherwise → Don't write it. Rename or restructure instead.
Private helpers never get doc-comments, no matter how complex — extract a well-named method instead of explaining a badly-named one. Rationale that isn't load-bearing for a future reader (ticket number, why you chose this approach) belongs in the PR description, not the file.
Recommendation▾
Add a couple of concrete before/after code snippets showing a full function transformed (comment removed, code renamed) rather than only single-line fragments, to strengthen the examples category.
Quick Reference
| Situation | Verdict |
|---|---|
| Restates what the next line already says | No comment — rename or restructure instead |
| Non-obvious business rule, regulatory constraint, or workaround | One brief line, at the point it applies |
| Public controller endpoint / interface member not self-evident from its signature | /// XML docs (JSDoc for exported JS) |
| Private helper, however complex | No doc-comment — extract a better name instead |
| Existing comment your change makes wrong | Fix or remove it in the same change — never leave it stale |
| Absence of something (a guard, a check) would read as a bug to a reviewer | A brief trailing comment heading off "why isn't this guarded?" |
By File Type
| File type | Don't | Do instead |
|---|---|---|
| C# | if (x) // active prescription | Name it: if (patient.HasActivePrescription) |
| C# controller | Undocumented GetById(int id) on a non-obvious endpoint | /// <summary>Returns the patient record, or 404 if not found or the caller lacks access.</summary> |
| Knockout/JS | // on submit / // proceed with save narrating a validation block | Split into a named function: submitClicked = () => { … } |
| HTML | <!-- Required text input --> above a field that already carries requiredMark | Nothing — the class already signals it |
| SCSS | .modalBlockout { z-index: 1300; } /* backdrop */ | Nothing, or a self-describing class name |
| Any | Silently omitting a guard other similar lines have | Brief trailing comment — the one case a comment earns its place, because its absence would look like a bug |
Reviewing Existing Code
- Comment your change makes wrong (renamed a concept, changed a constraint) → fix it in the same change, don't leave it stale.
- Clutter on a line you're already touching → remove it while you're there.
- Clutter on unrelated lines you happen to pass → leave it and flag separately, rather than expanding the diff.
Established Exceptions
Don't "clean up" these on sight — they're conventions with their own rationale:
- Unit test SAT comments and
#regionmethod grouping — organizational markers required by the test structure itself, not narrative explanation. - SQL migration comments — ticket tags (
-- CCRDEV-12341 Create new entities), idempotency guard comments, one-comment-per-sub-domain-folder convention. Operational metadata for whoever runs the migration, not "why" prose. - Elision markers inside reference docs (
/* options */,// … plain values …) — mark content the reader must supply, not comments meant to ship.
Common Pitfalls
| Mistake | Reality |
|---|---|
| "This block is tricky, it needs a comment" | Tricky code needs a better name or a smaller function, not a comment defending its trickiness. |
| "I'll leave a summary at the top of the method" | If the method needs a summary to be understood, split it — the summary is a sign it does too much. |
| "It's just one line, it can't hurt" | One-line comments are exactly what accumulates into the clutter this skill exists to prevent. |
| "The interface method is simple, but XML docs are free" | Free to write, not free to read — document only the members a caller can't infer from the signature. |