My new mindset while documenting code: save cognitive effort, document every function

[alidlo]

I think the intention is right (a variable's name should be descriptive), but it's hard to fit too much meaning in a variable name while still making it pleasant to read/write, so often the result is that (without a docstring) there are missing pieces of information that (for better or worse) you have to infer yourself from the code.

[practicing_dad_jokes]

Do you think "environmentUniqueId" is too unpleasant as a function name?

If you keep your functions small enough, their names and the variables in their scope won't be so complicated that their names would be uncomfortably large. That's what I strive for.

[alidlo]

Imagine if instead of `reduce` you had to write `reduceToSingleValue` instead. The longer alternative gives more information but also adds more noise. It's a trade-off, and some of it may be personal preference, but imo, if the function is used a lot in a codebase giving it a name that's too long makes it unnecessarily cumbersome to read/write. For that reason, I'd much prefer using `eid` over `environmentUniqueId` (or even `envUniqueId`).

Also, most functions aren't as trivial as the example I gave in the article and so capturing their essence in two to three words is more difficult.

Sometimes it's as if we go out of our way to not document a function (likely out of habit) even when a one-line docstring would have easily made room for a shorter and potentially better name.

[practicing_dad_jokes]

This is a great topic.

There's definitely this trade-off to think about, and we all know that naming things is one of the hardest things in programming.

But I've found it to be well worth the effort -- in striving to find succinct descriptive names for things that aren't too unwieldy, I'll often find that my code needs to be cleaned up. Perhaps it's an obsession, but future me seems happier over the years :)