Years ago I read the Google C++ Style Guide and watched an accompanying talk from Titus Winters. The guide is a superb technical document. But the thing that has stuck with me since is a sentiment behind many of the documented decisions:
Leave a trace for the reader.
This principle is also phrased “optimize for the reader, not the writer,” which is equally correct. But the concept of “leaving a trace” better captures the programming experience.
Debugging is detective work. You follow clues and retrace the culprit’s steps to solve the case. As a code author you are always a suspect. But remember: you are a suspect that wants to be caught. So leave obvious clues for future readers and detectives (including future you).
Code comments can be valuable, but there are more ways to leave a trace:
- Simple code (see Kernighan’s Law)
- Descriptive variable and function names
- Tree-like control flow
- Well-written test code
- Documentation, committed to source control, explaining high-level architecture, design, or technical decisions (anything that will be difficult to immediately deduce)
Prioritize readability. And getting caught.