A Study of Misunderstanding and its Remedies

In the chapter Choosing Names from A Philosophy of Software Design[2], John Ousterhout provides really good advice about how to choose names for the different elements that compose our software, like variables, functions, classes, and so on.

There’s one particular advice though with which I have trouble with. He writes about how to consider a particular name for a variable or method in our code:

“If someone sees this name in isolation, without seeing its declaration, its documentation, or any code that uses the name, how closely will they be able to guess what the name refers to? Is there some other name that will paint a clearer picture?”

From a linguistics point of view, I’m not sure how that would work. One aspect of words, is that they have meaning in context, not only in the sentence in which they are uttered, but in the socio-cultural environment that surrounds the utterance as well.

In 1936 I. A. Richards gave a series of lectures about The Philosophy of Rhetoric[3], where instead of being concerned with discourse and conflict, he was interested in the study of misunderstanding and its remedies. There he presents a sets of ideas that are really helpful when it comes to thinking about how to name things in software projects.

Let’s see what I. A. Richards has to say about the meaning of words:

A chief cause of misunderstanding […] is the Proper Meaning Superstition.

This superstition, he says, leads us to believe thinks like:

[…] a word has a meaning of its own (ideally, only one) independent of and controlling its use and the purpose for which it should be uttered. […] the stability of the meaning of a word comes from the constancy of the contexts that give it its meaning.

So it’s all about context. Something as simple as user.getRole() will have a different meaning if the user is a database connection user, or a user from a service like Twitter.

This problem is well known in linguistics as well, in the book Language The Unknown[1], Kristeva says:

The signification of [a] word can never be complete unless it is studied in discourse, while taking into account the enunciation of the speaking subject.

A Function of Distance

So what can we do about the naming problem in programming?

In this chapter Ousterhout presents a different opinion than his: one coming from the Go community, where they favor short variable names. He quotes Andrew Gerrand as saying:

long names obscure what the code does

Then he compares this code in Gerrand’s style:

Versus Ousterhout code, that uses longer variable names:

I’d argue that index variables are well known in the programming literature that calling them i or index won’t change much the readability of your code. Now I’m with Ousterhout when he says that the variable count gives a better clue about the code intent. Still, I’d be interested in hearing Gerrand’s quote from above in context to better understand what does he mean when he says that long names obscure what the code does.

Nevertheless, Ousterhout closes the chapter with a great quote by Gerrand:

“The greater the distance between a name’s declaration and its uses, the longer the name should be.”

Again, it’s all about context.

Meaning: A plant that has grown

Let’s close this article with a quote from Richards, about how we should think about meaning.

We shall do better to think of a meaning as though it were a plant that has grown—not a can that has been filled or a lump of clay that has been moulded.

This presents a generative metaphor–a plant that has grown– which we can use when we study the evolution of our own software projects, to understand how the meaning of our functions evolves as the project suffers different changes*.