[bravetraveler]

"Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish.

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.

[slily]

It depends on the domain. I would be cautious about assuming that concise comments explaining what is being done in a block of non-trivial code are unnecessary. I have seen too many people write code they assume to be trivial (after spending days/weeks/months/years developing necessary background knowledge to understand it) when it's not the case at all. Debugging errors in undocumented code that involves several complex/opaque structures, nested function calls, and external libraries is not fun when you can't tell what step is at fault due to side effects, internal computations etc. not being clearly visible.

[bravetraveler]

That's completely fair!

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

[bsder]

> "Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish.

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.

[froggit]

> 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."

[Groxx]

Yeah. It's deep-dive "oh God it's all terrible isn't it" discoveries, often containing some of the cursed knowledge that was obtained, not

    // this shit implements fizzbuzz
    fizzbuzz()