TheDoctor [they/them]

dozen = 12 + 1; // one extra for the baker!

I got mad at this when I first saw it but then I remembered there’s some code at work that defines an hour as 50 minutes

Statistically, this makes your code better

Yeah…. I’ve definitely been the next guy on a couple bad regexes that I wrote

When versioning and feature flags are too hard: just use git and hope for the best

My old senior used to do this before he got laid off and now I’m charge of code that’s littered with old commented out code and no way to know why it was commented out.

Then it breaks years after you’ve left and someone has no choice but to touch it

I often use comments as ways to say, “I know this is cursed, but here’s why the obvious solution won’t work.” Like so:

/**
 * The column on this table is badly named, but
 * renaming it is going to require an audit of our
 * db instances because we used to create them
 * by hand and there are some inconsistencies
 * that referential integrity breaks. This method
 * just does some basic checks and translates the
 * model’s property to be more understandable.
 * See [#27267] for more info.
 */

Edit: to answer your question more directly, the “why not what” advice is more about the intent of whether to write a comment or not in the first place rather than rephrasing the existing “what” style comments. What code is doing should be clear based on names of variables and functions. Why it’s doing that may be unclear, which is why you would write a comment.

Linux installs have gotten so quick and painless over the past decade or so. Usually just following a GUI, waiting like 5 minutes for the install, and suddenly you’re booted into a fresh desktop.