Guide when and how to write comments across source code languages.
npx skills add https://github.com/etylsarin/opencastle --skill code-commenting
Please help me install this Agent Skill. Skill: code-commenting Source: https://github.com/etylsarin/opencastle/tree/main/src/orchestrator/skills/code-commenting Command: npx skills add https://github.com/etylsarin/opencastle --skill code-commenting
This skill reduces noisy, redundant, and misleading comments by teaching when to avoid comments, when to explain rationale, and how to document public APIs so code remains readable and maintainable.
Apply the code-commenting guidelines to a function or module and rewrite comments to explain the reasoning and constraints rather than restating what the code does.
High-intent search queries and answers about installing and using this skill.
The best way to write code comments is to document rationale, constraints, and public APIs rather than restating what the code does. Use a decision framework to determine when to refactor or rename instead of adding redundant comments.
To avoid code comment anti-patterns during code review, look for obvious, redundant, and outdated comments. Apply a pre-commit quality checklist to ensure comments only document reasoning, TODOs, FIXMEs, and security notes.
You should add comments to complex logic when explaining rationale and constraints, but refactor or rename variables when the code can be made self-documenting. Use a decision framework to distinguish when comments are necessary versus misleading.
For documenting public APIs, use annotation tags for TODOs, FIXMEs, performance, and security notes. This ensures the API constraints and reasoning are clear during development and review workflows.
Yes, you can apply code commenting guidelines across languages for authoring and reviewing source code. The principles of distinguishing why versus what and avoiding redundant comments remain consistent regardless of the programming language.
atomicinnovationEvaluate code quality and maintainability across codebases without executing code.
phoenixvcExecute pre-delivery checks for quality gates, changelog, commits, TODOs, coverage, and documentation.
kcenonEnforce documentation standards for READMEs, API docs, and code comments.
mvillmowGenerate HTML or Markdown API reference docs from docstrings.
