Code Review Is Wasted on Style Comments

Fri, 31 Jul 2026 09:00:00 -0500

Code review has its highest leverage at the design level, not the style level. The questions that matter most are structural.

Are invariants maintained?

What does the system depend on being true, and does this change preserve that? This question catches whole classes of bugs a line-by-line read misses entirely.

// The invariant: a settled transfer always has a SettledAt timestamp.
// This PR adds a new status without touching that guarantee.
func markSettled(ctx context.Context, transferID TransferID, network string) error {
 return db.Transfers.Update(ctx, transferID, TransferUpdate{Status: "settled", Network: network})
 // SettledAt never gets set — nothing enforces it, nothing warns you
}

Line by line, this reads fine: it updates a status, it takes a network, it compiles. The bug only shows up when you ask the invariant question directly — “settled transfers always have a SettledAt” was true before this PR and isn’t after it. A line-by-line read has no way to know that invariant exists unless someone states it and checks the diff against it.

Code-Review on rjrowland

Code Review Is Wasted on Style Comments

Are invariants maintained?