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):

// 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:

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

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