Principles

The rules in later chapters are applications of five ideas. When a rule doesn't fit your situation, fall back to these.

1. Optimize for the reader

A line of code is written once and read dozens of times: in review, while debugging at 2 a.m., by the next person who has to change it, and increasingly by coding agents that copy whatever patterns they find. Every choice that saves the writer a minute and costs each reader ten seconds is a bad trade.

The practical test: can a newcomer explain what this file does after reading it once, top to bottom? If they need to jump around, keep four variables in their head, or read a comment to decode a line, the code isn't done.

2. Obvious beats clever

Prefer the boring construct. A for loop over a nested comprehension with a walrus. A plain class over a metaclass. A dict lookup over dynamic dispatch through getattr. A match statement over a hand-built visitor.

Cleverness isn't banned; it has to pay for itself. A clever 5-line function that replaces 60 lines of boilerplate is worth it. A clever 5-line function that replaces 8 lines of obvious code isn't.

3. Code describes the present

The source tree describes how the system works now. How it got here belongs in git history, PR descriptions and design docs. Comments like "we used to do X, but Y happened" and dead code kept "just in case" make every reader process a past that no longer exists.

4. Build for the load you have

Design for today's requirements, with seams where you expect change, not machinery for every imaginable future. A plugin registry for a tool with one plugin, or a priority queue for a server that has never had a second priority class, is complexity with no user. You can add it the week you need it, with real numbers in hand. See chapter 9.

5. Measure before you optimize

Performance structure (extra threads, extra CUDA streams, caches, pipelining) is the most expensive kind of complexity, because it's hard to read and hard to verify. Add it only when a profile shows the problem, and keep the profile's numbers in the PR description. If you can't show a timeline where the change helps, it doesn't go in.