IMO the skill of writing and maintaining good, useful comments is one of the things that distinguishes software engineering from mere programming.
I learned early in my software engineering career that sometimes even after a few months away from the code I wrote I couldn't remember all the fine details of the design. So I wrote comments for my own self-preservation, let alone giving another developer a fighting chance of knowing what's going on if they had to change my code.
On Sun, Jul 20, 2025 at 7:42 PM Larry McVoy <
lm@mcvoy.com> wrote:
Well, in a long lived code base, comments can rot. I'd much rather have
to read the code and figure it out than have a comment that is no longer
true send me down a wild goose chase (it's happened more than I care to
think about).
True, and that is why I've always considered the comments to be an integral part of the code, and when doing code reviews I've refused to approve code changes where the comments are too sparse or where the comments don't match the code.
-Paul W.