code-comments
/code-comments
What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages.
- Author
- zn-craft ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 09.11.2026
Assessment and security
- Files in this package
- 8
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 09.11.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
What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages.
Original author description
What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages.
How it works
- Find the rule for what you are changing
- Two hard rules
SKILL.md preview
--- name: code-comments description: What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages. --- # What a comment should say One test decides it: **if this comment disappeared, what would a reader lose?** If the answer is nothing, delete it. Anything the code already says stays out of comments — when a name, a structure or a type makes it clear, renaming, extracting a function or splitting a branch beats a comment, and that work belongs inside the current change without widening its scope. A comment earns its place by carrying what the code cannot: why it is done this way, where the constraint comes from, where the edge sits. Declarations that other code calls into get block comments (JSDoc / TSDoc, docstrings, Go doc comments) so hovers and completion can show them; implementation detail and inline logic get `//`. Comment language follows the comments already in the file; a new file follows the dominant language of its directory or repository, and one file never mixes two languages. ## Find the rule for what you are changing | What you are changing | Read | | --- | --- | | Config files of any kind: build, lint, CI, deploy, environment variables, container orchestration | [references/config.md](references/config.md) | | interface, type, enum, field semantics | [references/types.md](references/types.md) | | Constants, magic values, enum values, defaults | [references/constants.md](references/constants.md) | | Functions, methods, hooks, components, exported APIs | [references/functions.md](references/functions.md) | | Branches, loops, multi-step flows, test cases, workaround logic | [references/inline.md](references/inline.md) | | Markers for pending work, temporary logic, deprecation, commented-out code | [references/markers.md](references/markers.md) | A file header says what the file is responsible for and who calls it, in one line; read only the references listed above that you need, never all of them. Decide whether something is config by who reads it, not by its name: build, lint, CI, deploy, container and runtime readers make it config (`.prettierrc.mjs`, `vitest.workspace.ts`, `Makefile`, `.env.local`, `nginx.conf` all count); anything imported by product code is source. ## Two hard rules - An old comment is either made correct or deleted. A comment that reads right but is no longer true does more harm than no comment. - Leave no liabilities: commented-out implementations, debug leftovers and change logs all go. Their home is the commit history.
Files in this package (8)
- SKILL.md 3 KB
- agents/openai.yaml 1 KB
- references/config.md 5 KB
- references/constants.md 2 KB
- references/functions.md 4 KB
- references/inline.md 4 KB
- references/markers.md 2 KB
- references/types.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · zn-craft/agent-skills | 85 | MIT |
| zenobi-us/dotfiles | 100 | MIT |
| rp1-run/rp1 | 100 | Apache-2.0 |
| petekp/claude-code-setup | 100 | MIT |
| portabletext/editor | 100 | MIT |
| caidanw/skills | 100 | MIT |
| caidanw/skills | 100 | MIT |
| izumin5210/dotfiles | 95 | MIT |
| overmind-core/overmind | 90 | AGPL-3.0 |
Database snapshot: 13.11.2026 · package version 87971800ab76 (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
- 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… - 90no-comments
Delete the comments in a diff that the code should make unnecessary, through a fresh read-only reviewer, then fix the code each deleted workaround comment was excusing. Use before a change goes to review, or when the user asks to strip comments from a diff. - 100address-pr-comments
Address PR review comments by fixing code, replying to each comment, and re-requesting review. Use this skill when the user wants to handle, fix, resolve, or address PR feedback, review comments, or code review suggestions. Also use when the user says things like "fix the PR… - 100code-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. - 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… - 100comments
Comment rules for every language: which comments survive, format, protected comments, placement, TODOs. Use when writing, editing, moving or deleting comments, docstrings or TODOs. Auto-invoke when editing code files.