[daotoad]

Naming comments are useful when someone catches something like:

1. you are violating a previously agreed upon standard for naming things

2. inconsistent naming, eg some places you use "catalog ID" and other places you use "item ID" (using separate words and spaces here because case is irrelevant).

3. the name you chose makes it easy to conflate two or more concepts in your system

4. the name you chose calls into question whether you correctly understood the problem domain you are addressing

I'm sure there are other good naming comments, but this is a reasonable representation of the kinds of things a good comment will address.

However, most naming comments are just bike shedding.

[Arainach]

If the person reading the code doesn't quickly understand what's going on from the name or finds the name confusing, the name is poor and should be changed. It is way too easy for the author to be caught up in their mental model and to be unaware of their implicit assumptions and context and choose a name that doesn't make sense.

The bigger problem is people who feel ownership of shared codebases tied to their ego and who get angry when people suggest changes to names and other bits of interfaces instead of just making the suggested change.

If you get code review feedback, the default answer is "Done" unless you have a strong reason not to. If it's not obvious whether the name suggested by the author or the reader is better, the reader's choice should be taken every time.

[layer8]

> If the person reading the code doesn't quickly understand what's going on from the name or finds the name confusing, the name is poor and should be changed.

I used to think that way, but in many nontrivial circumstances, every conceivable name will be a mismatch for where some person is coming from, and not be self-evident for their mental model. Even the same person, over a longer time span. There is often a gap to bridge from name to meaning, and a comment isn’t the worst way to bridge it.

[hinkley]

I’ve seen this enough now to consider it a trope instead of a coincidence. There’s that one or two guys on the team who may be noteworthy in their math clever but only high school reading level, who use the same word in three parts of the code but use a different dictionary definition each time. They don’t see the big deal, they can keep it straight in their head, they insist. And if you can’t then you must be dumb instead of what you really are, which is sick of his bullshit.

Given enough time and rope, these parts of the code start to encroach on each other and the cracks start to show. There are definitely bugs the smart guy introduces because no, in fact, you can’t keep them straight in your head either.

So it does matter if you use, as a top of my head example, the word “account” for both the user and group management features of the app and to describe an entry to an incident report in another part. It will bite you in the ass, and it’s easier to change now when there are three references instead of 23.