code-comment-style
/code-comment-style
Write and tighten code comments so they state the why or the invariant in 1-3 lines. Use when adding comments to code, or when pruning verbose comments in a diff or PR.
- Author
- Sipty ↗
- Repository
- writing-skills ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Write and tighten code comments so they state the why or the invariant in 1-3 lines. Use when adding comments to code, or when pruning verbose comments in a diff or PR.
Original author description
Write and tighten code comments so they state the why or the invariant in 1-3 lines. Use when adding comments to code, or when pruning verbose comments in a diff or PR.
How it works
- Rules
- Before and after
- When tightening existing comments
SKILL.md preview
---
name: code-comment-style
description: "Write and tighten code comments so they state the why or the invariant in 1-3 lines. Use when adding comments to code, or when pruning verbose comments in a diff or PR."
---
# Code comment style
A comment is for a reader who has only the repo: no ticket, no PR thread, no chat that produced the code.
It earns its place by saying something the code cannot: why the obvious-looking version is wrong, which invariant must hold, or which constraint forced the shape.
## Rules
1. **Max 2-3 lines per comment.** If it needs more, it is explaining the wrong thing. Keep only the non-obvious invariant; cut narrative, chronology, and impact stories.
2. **One comment per concern, then "same treatment" for repeats.** Two identical loops do not each get a 6-line essay; the second gets `// Same upsert treatment for summaries.`
3. **No session artifacts.** No ticket IDs, PR numbers, reviewer names, dates, or plan step numbers in comments or test names. `describe('idempotent persist on recompute (PROJ-123)')` becomes `describe('idempotent persist on recompute')`. The PR and the ticket tracker own those references.
4. **No index or constraint-name recitals** when the column tuple says it shorter: `(account, timestamp, quality)` beats `reading_account_timestamp_quality_idx`.
5. **Explain why, not what.** "create() on an id already in the identity map resets the change-tracking snapshot, so the UPDATE is silently skipped" beats "set the fields on the entity".
6. **File and module headers** state purpose and the non-obvious decisions, not a changelog.
7. **Constants** get a short note on what they control when the name alone does not say it.
## Before and after
Before (5 lines):
```
// Flush the deletions before persisting: within a single flush the ORM runs
// INSERTs before DELETEs, so a recomputed row that lands on a slot
// (account_id, timestamp, quality) still held by a row with a different
// deterministic id would violate reading_account_timestamp_quality_idx and
// abort the whole flush, freezing the account's series (PROJ-123).
```
After (2 lines):
```
// Flush deletions first: within one flush the ORM runs INSERTs before DELETEs, so
// a replacement row would collide on (account, timestamp, quality) and abort the flush.
```
Before (5 lines, plus a near-identical twin further down):
```
// Upsert readings. For a reading that keeps its deterministic id, set the changed
// fields ... Only timestamp, value, quality and seqId are touched; id and account form
// the identity, and re-assigning the account relation would add the entity to ...
// For a summary that already exists, set the changed fields ... a second time.
```
After (3 lines + 1):
```
// Upsert readings: create() on an id already in the identity map resets the change-
// tracking snapshot, so the UPDATE would be silently skipped - set the fields on the
// loaded entity instead.
...
// Same upsert treatment for summaries.
```
## When tightening existing comments
- Never let a comment trim change code. If the comment sits next to declarations, re-read the region after editing and confirm the code lines survived.
- Re-run the affected tests after touching comments near test titles.
- If the repo has its own comment conventions (`AGENTS.md`, `CONTRIBUTING.md`, linters), they win.
Versions
The database has no other skills named code-comment-style.
Database snapshot: 13.11.2026 · package version aca39ab1799a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100code-comments
Write, review, or remove code comments. Use when adding comments or doc comments, reviewing the comments in a diff, or cleaning up or removing comments. - 100comment-review
Review and improve the code comments a PR or branch adds, against the standard in docs/developer/CODE_COMMENTS.md: cut the ones that restate the code, tighten the verbose ones, reframe what-comments into the why or the constraint, and add the contract docs the change left… - 100code-comments
Write high-signal code comments for humans and coding agents. Use when adding inline comments, docstrings, API comments, or local rationale near code. Triggers on: "write better comments", "comment this", "document why", "agent-friendly comments", "explain this code with comments", "docstring". - 100comment-hygiene
Curate source-code comments and docstrings — delete AI-slop and stale comments, keep only the non-obvious WHY, and never change executable code. Use when cleaning up comments/docstrings, during a samocode cleanup or quality-review step, when running /comment-hygiene, or when… - 100code-comments
Write high-signal code comments for humans and coding agents. Use when adding inline comments, docstrings, API comments, or local rationale near code. Triggers on: "write better comments", "comment this", "document why", "agent-friendly comments", "explain this code with comments", "docstring". - 100comment-cleanup
This skill should be used when the user asks to "clean up comments", "remove superfluous comments", "remove redundant comments", "trim verbose comments", "remove changelog comments from code", "clean up the README", or "run a comment cleanup" on a set of files or directories, or…