Commenting code is a more nuanced thing than we give it credit for.

There are a couple of schools of thought on this. One states that if you feel a comment is necessary, you should rewrite it to be more legible. This is true. But it’s also not true. In the process of writing a comment, you can often find things that could be written better, but it’s not an either/or, for the following reason: Code can describe how, but it cannot explain why.

There is just not one right way or one …