code-comment-generator
Code Comment Generator
Good comments explain why, not what. The code already says what. If you're narrating the code, delete the comment and make the code clearer instead.
What deserves a comment
| Worth commenting | Why |
|---|---|
| A non-obvious constraint the code depends on | "x is sorted here because caller guarantees it" |
| A tradeoff that was made deliberately | "O(n²) is fine — n ≤ 20 by construction" |
| Why the obvious approach is wrong | "Can't use .sort() — caller holds references into this list" |
| A workaround for an external bug | "libfoo 2.3 returns NULL here; remove when we upgrade" |
| Magic numbers with a source | "15s — AWS Lambda cold start p99 + margin" |
| Coupling to something far away | "Must match the regex in nginx.conf" |
| A subtle correctness argument | "Safe to read without lock: only written at startup" |
What does NOT deserve a comment
| Skip | Why |
More from santosomar/general-secure-coding-agent-skills
code-review-assistant
Performs structured code review on a diff or file set, producing inline comments with severity levels and a summary. Checks correctness, error handling, security, and maintainability — in that priority order. Use when reviewing a pull request, when the user asks for a code review, when preparing code for merge, or when a second opinion is needed on a change.
15dependency-resolver
Diagnoses and resolves package dependency conflicts — version mismatches, diamond dependencies, cycles — across npm, pip, Maven, Cargo, and similar ecosystems. Use when install fails with a resolution error, when two packages require incompatible versions of a third, or when upgrading one dependency breaks another.
4configuration-generator
Generates configuration files for services and tools (app config, logging config, linter config, database config) from a brief description of desired behavior, matching the target format's idioms. Use when bootstrapping a new service, when the user asks for a config file for a specific tool, or when translating config intent between formats.
3ci-pipeline-synthesizer
Generates CI pipeline configs by analyzing a repo's structure, language, and build needs — GitHub Actions, GitLab CI, or other platforms. Use when bootstrapping CI for a new repo, when porting from one CI to another, when the user asks for a pipeline that builds and tests their project, or when wiring in security gates.
3api-design-assistant
Reviews and designs API contracts — function signatures, REST endpoints, library interfaces — for usability, evolvability, and the principle of least surprise. Use when designing a new public interface, when reviewing an API PR, when the user asks whether a signature is well-designed, or when planning a breaking change.
2code-refactoring-assistant
Executes refactorings — extract method, inline, rename, move — in small, behavior-preserving steps with a test between each. Use when the user wants to restructure working code, when cleaning up after a feature lands, or when a smell has been identified and needs fixing.
2