The Immutable Past

Comments are important. I’ve written about them a bunch of times. Comments in docs. Comments in code. Comments in git commits and PRs. As an aside, git commit messages and Pull Request messages are often very different things with different intents.

All the old things still apply. Comment about why you did something, not what. Comment about what you decided to not do. Comment about when you might revisit the decision. The kind of comments that don’t go out of date as soon as someone else touches the code.

A quick heuristic that can help you know if you’re making a comment that won’t go out of date is to see if the comment makes sense if you prepend it with something like “On <today’s date> we wanted/needed/decided to/choose not to …”. That’s because the past is fairly immutable. The code (at the moment) says what was decided, and the comment says why.

The present, on the other hand, changes a lot. Our understanding of the domain will grow. The situation changes. What seemed correct then is wrong now. But the thoughts and reasons behind the decision didn’t change. They were valid when we made them, and that hasn’t changed, so those comments are still correct.

But now that we know more, whether by deeper understanding, the situation changing, a shifting goal, or something else entirely. So we want/need to change the code to match. And that’s a good thing. That’s being Agile. The situation changed, so we adapted.

We adapt the code, but we don’t need or want to change the comments. They’re recording a moment in time and that moment is still very real and very valid. We might add to the comments with our new understanding and why they old choice is no longer the appropriate one. But again, it’s documenting the why and the why not. Documenting the moment in time, right next to the code it’s relevant to.

What you don’t want to do is turn your comments into a changelog. After all, we have git (or whatever version control you’re using) to record the actual code changes.