code-commenting
Guidelines for writing self-explanatory code with minimal comments. Covers when to comment (WHY not WHAT), anti-patterns to avoid, annotation tags, public API documentation. Use when writing or reviewing code comments, docstrings, TODO/FIXME tags, code readability, or inline comments.
72
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
View guide
Passed
No findings from the security scan
Code Commenting
Comment WHY, not WHAT. When a bad name is the real problem, rename instead of commenting. Do comment: non-obvious algorithm choices, regexes, external API constraints, and the rationale behind every magic number or config constant. JSDoc every public API function.
Annotation Tags
TODO planned work · FIXME known bug · HACK workaround (say why and when it can go) · NOTE non-obvious constraint · WARNING side effect / mutation risk · PERF hot path · SECURITY security-sensitive · DEPRECATED (name the replacement and removal version).
Never
- Leave commented-out code — delete it; git has the history.
- Keep a changelog in comments — that is
git log. - Add decorative divider comments.
- Repository
- monkilabs/opencastle
- Commit
fa0c341
- Last updated
- First committed
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.