An important goal of good code is to be readable so that future contributors can build with and upon it as needed. Good commenting is part of the toolset for reaching that goal. In this post we shall first present principles of code commenting, and then a few tips.
I agree with the general thrust of Maelle’s argument. “What and how” types of comments are fine for pseudo-code that you write before beginning the real work, but they’re scaffolding and shouldn’t stick around when the code is done. Instead, focus on the “why.”
One area of focus I’d bring in terms of how I view comments is that I will have (and like to see) more detailed comments in the most difficult sections of code. Yeah, if you can simplify the code, that’s better than adding a lengthy comment. But there’s always some bit of code which five people have tried to simplify over the years but it doesn’t work. Knowing what the business rules are, what you’ve unsuccessfully tried in the past, and why this is the best available option (as of the time of the last update) can help prevent developer six from tilting at windmills.