Leaving a Trace

January 23, 2021

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.