Much has been said about comments in programming. I feel like when I was first learning “comment everything!!” was popular advice to newcomers which eventually shifted over to “your code should be self-documenting!”, though I suspect the latter advice has been around for about as long. I’ve never been a huge comment user since I wrote most of my code during short term contests, making it disposable. Mostly documenting things that might need to be adjusted later, possible problems/deficiencies, and often using them to separate unrelated chunks of code (which is likely a bad practice that generally indicates the code should just be split apart). I should do a better job of documenting the API, particularly considering how often I use dynamic languages.

But after working on such a long term project for so long, the realest purpose of comments is starting to dawn on me. Comments are band-aids for when things aren’t ideal. If you’ve analyzed a situation and decided to go with a compromise to get something done just “good enough”, you can use a comment to explain the particulars of an odd line of code instead of wasting the reader’s time figuring out the chain of reasons for it. I’ve probably used them for such a purpose countless times without realizing it. But there are just as many times where I’ve done something convoluted without bothering to explain it, and then had to understand it again later. I need to make a more proactive effort to notice these situations and then explain them for the future. It’s not as good as just having obvious behavior, but it’s better than nothing.

This isn’t a mind blowing revelation so much as reminding myself by writing about it. Most people writing about “self-documenting code” will say something very similar. Though they mostly refer to it as using comments strictly for non-obvious or complicated sections of code, as opposed to just admitting it’s to alleviate bad code. I don’t think I fully absorbed the idea when it was about “non-obvious” code. But bad code. That I understand.