Let’s skip the whole commenting is important because… part. That’s been dealth with. Here I’d like to share some thoughts about what drives me to comment code (or not) and, consequently, how it shapes my view of other developers work.
Driving Factors
There are two basic things that drive my commenting in code:
- Write to my future self
- Write what I wish I had found
My Future Self
This involves asking myself on a regular basis, and at the latest when submitting a change-set for review:
What will future me need to get up to speed in 6/12/24/… months for development or maintenance of this piece of software?
I think about future me because that’s the person I’m best at empathising with. And because I’m a quite lazy developer, the best way to please that person is to make its life as easy as possible when they pick up where I stopped.
Note how this requires you to actually care about a hypothetical future where you, and by a very small stretch others you care about, still touch things being worked on today. If you don’t care, there are probably deeper issues to look into.
What I wish I had found
We don’t develop in a vacuum (at least there’s always future me): we stumble across other’s work, and other’s pick up our output all the time. Thus, the golden rule applies: writing what I wish I’d find1 when being onboarded on a project or starting with a certain technology.
It’s slightly more subtle, as the comments will depend on:
- current level of expertise with what is being worked on
- level of expertise of the team
(And of course: how close the deadline is.2)
When learning something new, it’s hard to determine if what I write would be obvious to someone who is more knowledgeable. Thus a drive to over-comment and explain what’s going on: it’s easy to delete silly comments during review.
Conversely, while I may be well versed in the details of what I do, what about the colleagues that will work on that piece? How would a fresh hire fare if they’re not experienced with this technology?
This gives a quick heuristic I abuse over and over again:
| Team\Self | Low XP | High XP |
|---|---|---|
| Low XP | Over comment & explain, squared | Over comment & explain |
| High XP | Higher pressure to comment | Normal pressure to comment |
Yes, the bias is heavily in favour of comments. Gotta please that lazy future me.
Final Word
While not quite a maximalist as the code should annotate comments crowd, I’m a fan of over commenting, as long as the comment brings something, even if it’s only a joke that tries to lighten some particularly ugly contorsions.
Searching for a different quote by D. Knuth, I ran into this one that’s tangential to what’s on my mind:
Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. [Donald Knuth]
Modern software projects are a pretty complex environment: carefully crafted comments in a codebase will go a long way in helping you, future you and colleagues navigate it.
Happy commenting!