As the joke goes, “There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors.”

In truth, one of most difficult things in software development might be comments, and the more experience you have developing software, the harder it becomes.

There are some things that should be very obvious about comments at some point. Comments should explain why, not what. Well written code will tell readers what is happening, but not necessarily why. A developer may look at a block of code and unerstand that this code builds a data structure… Why does it do that? How is the data used later? How much memory does the structure cost, and how much does that improve run time? If you don’t know the answer to these “why” questions, it’s hard to tell whether things work as expected in the future. The same is true for commit messages. The diff tells a reader what is being changed, the commit message doesn’t need to describe that. Why is it being changed?

That’s the easy part.

The hard part is the question: what will the next developer to work on this know, and what do they need to be told?

You might be familiar with the the Dunning–Kruger effect. Their paper illustrates that skill exists along a spectrum, and both people at both ends have a poor understanding of people at other points along the way.

Without a clear understanding of what the typical developer understands, it is very difficult to write comments that answer “why” questions that most developers will have. An experienced developer will tend to describe too little, assuming that most developers already know what they need to know to contrubute. It can be especially difficult for experienced developers to overcome that tendency, and offer those explanations, because explaining things that seem obvious to them will, at some point, feel condescending.

My advice, or perhaps my request, to all developers is this: ask yourself why code needs to do what it is doing, and explain that as if to a student developer. Explain it more than you think you need to. Write until it is embarrassing to write. Tell yourself that the embarrasment is the cost of experience.