recently spoke about comments
it shouldn’t really be a whole thing, but these are the types of hills we die on as programmers, thought it was worth sharing and expanding on my thoughts as much as i could as the original reply was getting pretty long
this is all entirely feeling-based, has changed over the years, and none of it is a hard rule, i try to be measured here and highlight the nuances instead of “pick a side”, none of us are in pre-k, so that shouldn’t be unreasonable
*if you are in-fact in pre-k, go learn vim bindings instead of reading this braindump, way more useful
got a dyslexia thing going on and sparingly use comments as visual/mental anchors between steps or sections (though only if they are significant, not out here commenting three lines)
keeps things clear and more like a note in obsidian with headings, just qol though and easier to grep, added bonus is setting up jump point macros as well, can and often do go without, esp if i’m in someone else’s codebase- very important.
this has been received positively and (usually blindly) negatively by colleagues and peers in the past, though even when dealing with a “comments always bad” type person they come around when the intent and sparing/strict nature of them is explained
it is rare that i comment a block of code to explain it, sometimes a file will be a tad complex and it is easier just to dump “what this crazy thing does” at the top just for passing readers if nothing else, but if you are doing that on a block/function/line level hope you ready to defend it (things like jsdoc etc. aside)
all this being said i wish comments had a strong and rot-proof place in the world, zero drift, perfectly useful and usable both for and with tooling, exported to low-to-zero effort documentation that is always in sync to the state and functionality of the code
would require a total re-conceptualization and mindset shift, or appropriately powerful and widely used/agreed-on tooling
original reply: here
this is all situational
if i am in a complex low-level/embedded codebase, or in a shader doing a chunk of complex math, or more obviously something consumed by users rather than just me and my team, then naturally i am more likely to be willing to both accept and write detailed comments when necessary and appropriate
if we are talking about a html file and have a h1 tag, with a comment above saying “post title”, that is wild, don’t do that.
my last couple thoughts about a conceptual framework for useful and rot-proof comments- this is a thing i have felt was “missing” for a while, some way of having all of these details regardless, and the ability to see them when you need but not clutter your space when you don’t, the ability for a tool to potentially check that they haven’t drifted and are sufficiently “useful”, almost like a sanity linter
this doesn’t sound quite as far-fetched now we are in the era of machine learning
clearly we need comments sometimes but not all the time, it sucks when you are using something and the comments/docs are awful and it makes navigation suck, hitting a huge chunk of logic and having to reverse engineer it because it is not self-descriptive and lacks any kind of documentation, with a git commit message “fix: made it work”- this is also wild, don’t do this.
if you write too many comments, or if you despise them without exception, you are probably wrong, but your feeling might not be unjustified
comments are sometimes useful, and a well intended comment at the right place in a sufficiently complex web of code can save hours, but they are also often a code smell and signal a larger problem in the codebase. worth taking a step back sometimes to evaluate this
like with all good users of innocently vilified tools, a good programmer should have a strong sense of when to use comments, but most importantly when not to comment at all
i wish you all the best in navigating this minefield, though i can’t help but wonder about a bigger picture and brighter future for the humble comment
more of a technical one today, huh?
〆 alia