Keep a lab notebook for your code
The habit that made me a scientist turned out to be the one that made me a better programmer.
In the lab, the rule was simple: if it is not in the notebook, it did not happen. Every experiment got a date, a hypothesis, what we actually did, and what we saw, including the things that went wrong.
When I moved to writing code for a living, I stopped doing this. Code has version control, I thought; the history is already there.
It is not. Git records what changed. It does not record what I expected, what I tried first, or why the obvious approach did not work.
What goes in
I keep one running note per project. Each entry is short:
- the date, and what I am trying to find out
- what I tried, including the command or query
- what happened, pasted rather than paraphrased
- what I think it means, marked as a guess
Why it works
Most of the value is in the dead ends. A month later, when the same bug comes back, the note says I already tried the cache, the cache was not it, and here is the output that proved it. That is an afternoon saved, every time.
It also changes how I think while working. Writing “I expect this to fix it” before running the fix makes it obvious, surprisingly often, that I do not actually expect that at all.