Writing for the second reader

I used to think of documentation as something for other people, a README for the team or a comment for the reviewer. Lately I think the first reader I should write for is my future self, who opens the file with no context at all.

That reader needs very little. A sentence about what the module is responsible for. A note on the one decision that looks wrong but isn't. A pointer to the test that proves the edge case works. Most of my comments now answer one of those three questions.

If a comment only repeats the line below it, delete the comment.

The harder habit is resisting the urge to explain everything. Long comments drift out of date faster than code does, and they teach people to skip comments entirely. I try to write only what the code cannot say on its own. The Google engineering practices guide has a good section on reviewing code for clarity that makes a similar point from the reviewer's side.