When I started programming, my teachers insisted I comment my code. Everything to show what I was doing in the code. Partly they may have wanted understandable, mark-able code. They insisted it was best practice so others (or your later self) could understand the code.
Programs I found at my work did not have comments the way my teachers had required. Moreover, the few existing comments pointed me in the wrong direction to understand the code. What was going on?
Bob Martin describes this as “Comments rot.” As the requirements change, the programmer rarely updates the comment since it’s not part of the workflow. Nothing in the compiler checks the comments’ correctness.
Martin goes on to suggest naming your variable well is better. My teachers taught me the commenting tradition from the days of one or two-character variable names.
Proper variable and function naming should take the place of comments.
I think we can agree, that well-named functions and variables help a lot in understanding the code.
Do variable names rot? Can the code change and start making the variable names incorrect? You betcha. Possibly not as fast, but with time they will.
Consider my first name: Alan. According to what I can find, it derives from a word meaning handsome. Am I? Is every Alan in the world handsome? Based on commercials and movies I see, most often dorks have my name.
The current King of England’s name means peasant. How is a king a peasant?
Human names rot. Variable names rot. Function names rot. Class names rot. Comments rot. Every name becomes entropy and disorder. We have to plan for the rot to overcome it.