The core idea is simple: a module should have a small interface and a lot of functionality behind it. Ousterhout calls this a deep module. A shallow module has an interface almost as big as its implementation, so it adds cost without hiding anything.
Three things stuck with me:
- Complexity is incremental. No single decision makes a codebase hard to work in. Hundreds of small “just this once” choices do.
- Define errors out of existence. The best way to handle an edge case is to design the interface so the case cannot happen.
- Comments should say what the code cannot. If a comment repeats the code, delete it. If it explains why, keep it.
The deep-module idea carries straight over to agent tools. A tool that takes a topic and returns a finished result is deep. A tool that exposes every knob is shallow, and the model has to learn all of them.
Short book. Read it twice.