There are only two hard things in Computer Science: cache invalidation and naming things. — Phil Karlton

Usually, when I have heard this quote on the difficulty of naming, it’s been mentioned in reference to macro-scale situations. You have some class or service that feels like its own grand self-contained concept, but you can’t for the life of you figure out what it should be called. But at the micro-scale of individual function and variable names, there is a far more pervasive and subtle naming problem in software development: unnoticed ambiguity, and in particular, ambiguous parts of speech.

Ambiguous words are everywhere

Consider the following English sentence, which might describe some logic around retry backoff:

Increase the delay if the request hits a timeout.

Because of its structure, the meaning of this sentence is fairly clear. Yet, out of context, every single noun in that sentence can also function as a verb, and vice versa.

Now let’s look at a related chunk of code, which partially implements retrying requests with backoff:

Beyond the obvious lack of comments, this code is difficult to read, and understanding the purpose of each of these lines is hard. The fundamental issue is that while each identifier accurately describes its subject, most of these names are ambiguous. For example, does fetchArgs fetch arguments from the server, or does it provide arguments to the method called fetch? Better naming can make this quick, easy, and unambiguous to read.

There are several factors that contribute to this problem. The first is that code does not provide the same context that human languages convey. Words like “the” and “of” are often omitted in code, and discerning a word’s part of speech — a preliminary step in inferring its meaning — is often impossible without a deeper understanding of the code surrounding it. Sometimes this is virtually unavoidable, but when the surrounding code contains even more examples…