skills.rest
marjorg
marjorgCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

comments

Guides writing minimal, high-value code comments and TODOs during code editing.

1|Updated Mar 2, 2025
Search Tags:#code review#documentation#refactoring#clean code#code comments#dead code#todo
One-click install
npx skills add https://github.com/marjorg/setup --skill comments-marjorg
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: comments
Source: https://github.com/marjorg/setup/tree/main/home/.agents/skills/comments
Command: npx skills add https://github.com/marjorg/setup --skill comments-marjorg

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate noisy comments that restate the code, outdated file headers, and vague TODOs that no one can act on. This Skill enforces a disciplined standard so every comment that survives carries information the code itself cannot express. ## Core Features & Use Cases - Comment decision rule: A two-question test (is the fact absent from the code, and would it surprise a competent reader) decides whether a comment earns its line. - Content guidelines: Defines what passes (non-obvious constraints, external API quirks, traps, pointers to issues or specs), what to cut (restated code, section banners, change narration), and how to handle file headers, TODOs, and dead code. - Use Case: While editing a payment integration, you add a one-line comment noting that the vendor returns 200 with an empty body on rate limit, with a link to the tracking issue, instead of a five-line essay. ## Quick Start Review the comments in this file and remove or rewrite any that restate the code, then fix the TODOs to include an actionable reference.

Frequently Asked Questions about comments

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I decide whether to write a code comment?▼

Ask two questions: is the fact absent from the code itself, and would a competent reader be surprised by it. Only if both are yes should you write the comment, keeping it to one or two lines.

What kinds of code comments are worth keeping?▼

Keep comments explaining why a non-obvious approach was chosen, constraints from outside the code like undocumented API behavior, traps that look safe to change, and pointers to issues, RFCs, or specs that settle the design.

How should I write a good TODO comment?▼

A useful TODO states what should happen and points at whatever settles it, such as a ticket number. For example, reference the issue and the condition for removal rather than leaving a bare TODO marker.

When should I write a file header comment?▼

Almost never, since the name, path, and package already identify the file. Write one only when a reader would be wrong about the file after seeing those, such as a debug shim that looks like the production entry point.

Should I keep commented-out code for reference?▼

No, delete code you replaced because version control already holds the history. A commented-out block tells readers nothing except that someone hesitated, and it rots as the surrounding code changes.

Related Skills

Explore More Software Engineering Skills→
zhiyuan-zhang0206zhiyuan-zhang0206
1

implementation

Guides writing and refactoring code with precise naming, domain alignment, and intentional comments.

Community
Intermediate
Nandansai08Nandansai08
1

code-comments-that-last

Guides writing and reviewing code comments and docstrings that survive refactors.

Community
Intermediate
smart-swimmingpoolsmart-swimmingpool
25

cpp-code-quality

Run clang-format, cpplint, editorconfig-checker, markdownlint, yamllint, and platformio check on C++ projects.

Official
Intermediate
nholder88nholder88
2

code-documentation

Generate language-native documentation comments for exported symbols across codebases.

Community
Intermediate