name	comments
description	Automatically adds useful inline code comments to new or changed code. Triggers after code edits.

Code Comments Skill

After writing or editing code, review the changes you just made and add inline code comments (//) where they would help a reader who lacks project context understand the code.

What makes a comment worth adding

A comment is worth adding when a reader without context would struggle to understand why the code does what it does. Good comments:

Explain the why behind a design choice, not the what
Reference protocol behavior, spec requirements, or external constraints that justify the approach
Preempt confusion — if a reader might think "is this a bug?" or "why not do X instead?", the comment answers that before they ask
Clarify non-obvious invariants or assumptions baked into the code

Example of a good comment

// The Kafka protocol only requires correlation IDs to be unique among
// in-flight requests. The server echoes back whatever the client sends.
// Sequential generation is a convention (used by both the Java client
// and librdkafka), not a protocol requirement.
// For this reason, the sending order doesn't guarantee correlation ordering,
// i.e. the task can be yielded between this line and the send below.
// This is fine.
let correlation_id = self.next_correlation_id.fetch_add(1, Ordering::Relaxed);

This comment works because it explains why Relaxed ordering is safe by referencing the Kafka protocol spec and addressing the natural "is this a race?" concern.

What to avoid

Never restate what the code does (e.g. // increment counter above counter += 1)
Never add comments to self-explanatory code
Never add doc comments (/// or //!) — those are handled separately
Never add TODO/FIXME comments unless the code is intentionally incomplete
Keep comments concise — a few lines max, not paragraphs

How to apply

Look at the code you just wrote or changed
For each non-trivial block, ask: "would a reader without context understand why this exists or why it's done this way?"
If no — add a comment that gives them the missing context
If yes — leave it alone
Place the comment directly above the relevant line(s)

Code Comments Skill

After writing or editing code, review the changes you just made and add inline code comments (//) where they would help a reader who lacks project context understand the code.

What makes a comment worth adding

A comment is worth adding when a reader without context would struggle to understand why the code does what it does. Good comments:

Explain the why behind a design choice, not the what

Reference protocol behavior, spec requirements, or external constraints that justify the approach

Preempt confusion — if a reader might think "is this a bug?" or "why not do X instead?", the comment answers that before they ask

Clarify non-obvious invariants or assumptions baked into the code

Example of a good comment

// The Kafka protocol only requires correlation IDs to be unique among // in-flight requests. The server echoes back whatever the client sends. // Sequential generation is a convention (used by both the Java client // and librdkafka), not a protocol requirement. // For this reason, the sending order doesn't guarantee correlation ordering, // i.e. the task can be yielded between this line and the send below. // This is fine. let correlation_id = self.next_correlation_id.fetch_add(1, Ordering::Relaxed);

This comment works because it explains why Relaxed ordering is safe by referencing the Kafka protocol spec and addressing the natural "is this a race?" concern.

What to avoid

Never restate what the code does (e.g. // increment counter above counter += 1)

Never add comments to self-explanatory code

Never add doc comments (/// or //!) — those are handled separately

Never add TODO/FIXME comments unless the code is intentionally incomplete

Keep comments concise — a few lines max, not paragraphs

How to apply

Look at the code you just wrote or changed

For each non-trivial block, ask: "would a reader without context understand why this exists or why it's done this way?"

If no — add a comment that gives them the missing context

If yes — leave it alone

Place the comment directly above the relevant line(s)