code-commenting
Guidelines for writing self-explanatory code with minimal comments. Covers when to comment (WHY not WHAT), anti-patterns to avoid, annotation tags, and public API documentation. Use when writing or reviewing code comments, docstrings, TODO/FIXME tags, code readability, or inline comments.
100
Quality
100%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Securityby
Passed
No known issues
Code Commenting
Comment WHY, not WHAT. Prefer renaming over commenting.
When to Comment
| Situation | Action |
|---|---|
| Self-explanatory code | No comment |
| Bad name is the real problem | Rename instead |
| Complex business logic / non-obvious algorithm | Comment WHY |
| Regex, API constraints, gotchas | Comment WHY |
| Public API function/method | JSDoc |
| Magic number / config constant | Inline rationale |
Examples
// ✗ Obvious
let counter = 0; // Initialize counter to zero
// ✓ WHY
// Apply progressive tax brackets: 10% up to 10k, 20% above
const tax = calculateProgressiveTax(income, [0.1, 0.2], [10000]);
// ✓ Algorithm rationale
// Floyd-Warshall: need all-pairs distances, not just single-source
for (let k = 0; k < vertices; k++) { /* ... */ }
// ✓ API constraint
// GitHub API: 5000 req/hr for authenticated users
await rateLimiter.wait();
// ✓ Config rationale
const MAX_RETRIES = 3; // network reliability baseline
const API_TIMEOUT = 5000; // Lambda max is 15 s — leave headroomPublic APIs — JSDoc
/**
* @param principal - Initial amount
* @param rate - Annual rate as decimal (0.05 = 5%)
* @param time - Years
* @param n - Compounds per year (default 1)
* @returns Final amount
*/
function calculateCompoundInterest(principal, rate, time, n = 1) { ... }Annotation Tags
| Tag | Use |
|---|---|
TODO | Planned work |
FIXME | Known bug needing fix |
HACK | Workaround — note why and when to remove |
NOTE | Important non-obvious constraint |
WARNING | Side effect / mutation risk |
PERF | Hot path — optimization opportunity |
SECURITY | Security-sensitive code |
DEPRECATED | Note replacement and removal version |
Anti-Patterns
| Anti-pattern | Rule |
|---|---|
| Commented-out code | Delete it — git has history |
| Changelog in comments | Use git log |
| Decorative dividers | Use proper file/section structure |
Checklist
- Explains WHY, not WHAT
- Still accurate after the change
- Adds genuine value
- Placed above the code it describes
- Repository
- monkilabs/opencastle
- Commit
f5c8508
- Last updated
- Created
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.