I tend to treat them like a strange hybrid of a story with editor's notes.
Here's where we're going... but oh no! Something is in the way. We need this critical, but painful to acquire shovel.
If I anticipate even the slightest bit of refactoring around it, I'm noting what devilishness lead me down this path.
TLDR: anything that could be abstracted away/not exist, probably deserves comments on why it does... perhaps even how it could be removed.
There have been cases where very slight changes in methodology completely fall apart - reasons varying. Timing, cache fit, and whatever else you may think of.
Jenkins is something I've been picking up lately, and the 'DSL' has a ridiculous number of quirks
And "profanity" in code is almost by definition a "Why"-type comment.
You don't get upset and leave a profane comment unless you did a deep dive and realized the code does something absurdly horrible that took you far too long to figure out.
This describes my profanity use in comments perfectly. I'll even increase the amount of profanity and "descriptive phrases" depending on the frustration level I peak at.
Fun fact: my profanity will always be formatted into proper, grammatically and contextually correct sentences. This seems counterintuitive.
I'm curious what kind of profanity other people use; whether anyone else has an oddly specific format or if it's more off the cuff. (fyi: edited to not be cussing on HN, there will be a 100% chance my first profanity will be :"f###ing bulls##t," this is usually enough. In more severe cases I'll generally add: "bloody h3ll," "raging dumpster fire," "dumbest s##t ever," "d#mnation! h#llfire!," and, when I've completely lost my s##t, "what in the actual f###ing s##t is this g##d##n f###ing bats##t f###ing insane s##tshow clusterf##k!"
It saves a lot of time down the road to know whether I got pissed, super pissed, pissed af, threw some random s##t, or "welp, it's 5 o'clock somewhere."
// this shit implements fizzbuzz
fizzbuzz()Any tester is going to need detailed information that is devopsy and cannot be expressed in pure code (Despite the claims spoken by the code-as-infrastructure tools).
There are also cases where I like to document the living shit out of my classes/functions if they are something that will be used by many other devs. Bash/unix functions are some of the most heavily-documented tools you will ever see. Try using 'man grep'.
There are more questions than "why" that can be answered by comments. There are also "What ifs" that you could anticipate. Many of those "what ifs" are almost certain to appear in certain circumstances, and I choose to drop a few breadcrumbs that can save the code maintainers a few weeks of their time rather than following a false lead.
The beauty of code comments is that they don't require some external tool. They are in the pudding with the code itself, where they can be found easily. Most IDEs allow you to collapse long comments and even fade comments into a light grey so they aren't distracting.
From this thread and work experience I know that the code commenters are losing our war and are pretty much defeated by the code aesthetics crowd - who insist code should be beautiful before being useful.
I disagree about the "how", at least for challenging to read sections of code. In these instances, it is not good to assume that everyone who is reading or modifying the code is an expert in the language or problem domain, so it's good to explain to them how code solves the problem.
Explaining how the code works is very different than explaining what the code is doing. For example, something like "This code takes input sets of timestamp data and uses a timestamp keyed hash map to bucketize them by n minute interval".
That is very different than explaining how at each step you look at each time stamp and bucketize it, then generate a new time stamp bucket key and add it to the hash map.
The first approach explains at a very high level what's happening technically so that the reader can more easily understand the operations needed to accomplish the objective.
Ie:
def drive
turn_ignition()
shift_gear()
press_accelerator()
end
def turn_ignition
… code
end
def shift_gear
…`def start_the_car_and_accelerate`