Everyone I've worked with agrees that naming matters. Almost nobody spends any time on it. The name gets picked while the code is half written and then it sticks, because renaming feels like fuss once the thing works. I've had this conversation in enough reviews to think the problem isn't the principle. It's that the principle doesn't tell you what to do with this function, today.
The check
I read the function name and the parameters and try to say in one sentence what the call does. If I can do that without opening the body, the name is fine. If I can't, one of two things is wrong. Either the name is bad, or the function is doing two jobs and no single name will cover it. In my experience it's the second more often than you'd think. A function that won't take a sensible name usually needs splitting, so I run this before I look at length or complexity. It finds the same problem earlier and with less arguing.
Where the names come from
The best names are the ones the product owner already uses. The worst describe the machinery, and they're the same handful in every codebase: process, handle, manager, helper, data, info, tmp. Each is a placeholder for a noun nobody has bothered to find yet, and review is where you find it. None of this is new. Robert C. Martin covers it in chapter two of Clean Code (2008) and Martin Fowler lists the opposite as the Mysterious Name smell in Refactoring (2018).
What I'd add is that the type should agree with the name. A parameter called id typed as string takes anything the compiler thinks is a string, which is everything. Call it userId, give it a UserId type, and the call site, the signature and the compiler all say the same thing.
The objection
The usual objection is width. Eight honest words wrap worse than eight abbreviations, and some code, mostly maths and crypto, borrows its abbreviations from the paper it implements. Both are fair. Width is an editor problem and the wrap setting moves. For code that follows a paper, the abbreviation is the honest name for the people reading it, so cite the paper next to the module and leave it. For ordinary application code I'd hold the line. If a name is long because the idea is long, you want a domain type or a smaller function, not mgr.
Why it matters more with agents
Agents have made me stricter about this. They abbreviate out of habit and it's easy to wave through proc because the prompt said processing. A developer who meets proc(o) six months later opens the body and works it out. An agent takes the name at face value and builds on it, so one lazy name becomes the vocabulary for everything written around it. By the time anyone notices there's a lot of code that assumes the bad name was a fact.
Absolutely, let's be pragmatic about this. The naming rule is one line in our rules file: a reader of the name and parameters should know what the call does. A placeholder name sends the change back rather than going on a list to tidy later. That one line has done more for readability than any style guide I've written, and I've written a few.
The longer version, with the sources and the counter-argument, is at https://prickles.org/tenet/intention-revealing-names/F2
Top comments (0)