# Comment Non Obvious Steps

> Use when writing or editing code that contains repeated-looking calls on different structures, bitmask/bit-fiddling, ordering-sensitive sequences, or multi-step state mutations across data structures — adds a short inline comment per step explaining WHY each step is distinct, so a reader doesn't stop and ask "wait, why are there three of these?". Does not apply to trivial code with self-explanatory identifiers.

- Skill: `amitkot/comment-non-obvious-steps` (Agent Skill)
- Install (CLI): `npx skillmds@latest add amitkot/comment-non-obvious-steps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amitkot/comment-non-obvious-steps/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: amitkot (https://skillmd.com/u/amitkot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/amitkot/comment-non-obvious-steps

---


# Comment non-obvious steps; explain the WHY, not the what

Default is no comments. The carve-out: when a step's intent isn't obvious from the identifiers — repeated-looking calls on different structures, bit fiddling, ordering-sensitive sequences, or the same field mutated at multiple layers — add a brief inline comment per step explaining WHY this step is distinct.

## Why

A future reader (often the same human, a week later) scanning the function shouldn't have to stop and ask "wait, why are there three `remove()` calls — is one redundant?". One short comment per step turns "I have to reverse-engineer this" into "ah, secondary index, then primary store, then GC". The comment is the difference between a 10-second read and a 5-minute investigation.

This does NOT contradict "no comments by default" — trivial code with self-explanatory names still needs none. The trigger is: a reader will plausibly stop and ask why.

## How to apply

Add a comment when a step is one of:

- One of several similar-looking calls on different structures (3x `remove`, 2x `insert`, etc.)
- Bit manipulation / bitmask arithmetic (`x & !FLAG_FOO`, `bits >> 3`)
- Ordering-sensitive (must run before/after the next step) and the order isn't enforced by types
- Same logical field mutated at multiple layers (cache + store + index)

Comment the WHY/WHAT-IS-DIFFERENT, not the what. `// remove from cache` is noise; `// drop cached view so next read repopulates from primary` earns its line.

## Examples

Multi-remove (the live case):

```rust
// BEFORE — reader: "why three removes?"
self.by_sender.remove(&sender);
self.orders.remove(id);
self.parents.remove(&group_id);

// AFTER
self.by_sender.remove(&sender);          // secondary index
self.orders.remove(id);                  // primary storage
self.parents.remove(&group_id);          // GC empty parent group
```

Bitmask:

```rust
// BEFORE
flags = (flags & !0b0011) | (new & 0b0011);

// AFTER
flags = (flags & !0b0011) | (new & 0b0011); // replace low 2 priority bits, keep upper flags
```