Code is written once and read many times. Your code will live far longer than you probably think, and some poor soul will need to change it long after you’ve moved on.
While this should elevate the importance of genuinely useful comments, I rarely see comments which explain why code exists, what else was tried (that failed), and after minutes or hours of research, what specifically convinced the dev that this particular implementation was worth using.
I feel like this topic is programming 101 – good comments explain why! – but even “good” developers consistently fail to do it.
And now a real example:
Without the comment, some clever dev might think “This is wrong. Debian Jessie
sets the localedef and here it’s set again! This is safe to remove.”
But you know what? I spent over an hour tracking down
localedef issues in
this container. I am absolutely sure that “cleaning up” those lines
will break the environment.
Again without comments, some hotshot (probably me, 8 months down the line)
will think “The DB docs say that slugs have a max length 20. If
I constrain the length here, then our column will enforce the rule.” …and
they would be wrong. It’s not common knowledge that
support length modifiers. Sure, they’d find out after a quick Google search,
but how long will it take to figure out that we’ve used a RegEx constraint
instead? Too long.
This type of comment I consider most important. For anyone new to your codebase, security decisions are most critical to understand. If your decisions are locked away into some “Security Architecture of Project ABC” PDF file, then you’ve failed. Make your security critical code read like a book; it sets up the maintainers to win.