[alembic_fumes]

Back when I programmed in Haskell, I also had a similar question about the extremely terse variable names that pop up everywhere. I'd wonder, why is this "x" and "xs" instead of "item" and "items" or "businessName" and "businessNames" or whatever. Eventually I found this (paraphrased) answer that made it all click:

The specificity or abstractness of a (variable) name relates to the values that it can hold. So when you have a very abstract function whose inputs can be of almost any type, naming those inputs in an overly-specific manner is an exact inverse of the failure of giving an overly generic to name highly constrained parameter.

Examples of correct naming:

  func firstWord(s string) string { ... }

  func bidShortcodePrefix(businessId string) string { ... }

Examples of incorrect naming:

  func firstWord(strWithOptionalSpaces string) string { ... }

  func bidShortcodePrefix(s string) string { ... }

All this said, I do agree with your original take on the comments. I much prefer having human-readable explanations inline with anyhow non-trivial code. If nothing else, they really make it easier to correctly fix the code if a bug is found much later.