Design It Twice

Your first idea is rarely the best one. Settle the interface before you write any implementation.

Process

1. State the need. Write down what callers must do in the common case, as 2–4 concrete call sites.
2. Sketch 2–3 radically different interfaces. Signatures plus a one-line comment each. No bodies. If only one design seems reasonable, still sketch a deliberately different one: its weaknesses teach you something. For large designs, run one sub-agent per alternative in parallel.
3. Write the common-case call sites for each alternative. The design that makes callers write extra glue loses.
4. Compare, most important criterion first:
   • Ease of use for the common case (higher-level code stays simple)
   • Interface simplicity (fewer methods and concepts, same power)
   • Depth (how much it hides)
   • Generality: somewhat general-purpose, meaning the functionality serves today's needs but the interface isn't tied to them
   • Whether it allows an efficient implementation
5. Synthesize. The winner is often a hybrid. If every option is awkward, turn the shared awkwardness into a requirement and design again. (Line-based and char-based text APIs both force callers to do text manipulation, which leads to a range-based API.)
6. Repeat for the implementation when it's non-trivial. For implementations, weigh simplicity and performance.

Useful questions