On the Naming of Methods

Methods are functions which are bound to a particular object.  The exact mechanism changes depending upon the language, but the general idea is that you don’t ever call them without knowing what object they belong to, and the that code inside them has access to the object.

Conceptually, this “binding” means that calling a method can more accurately be thought of as making a request of the object.  Imagine a class like this one:

class Dog(Animal):
    def __init__(self, name):
        self.name = name

    def speak(self):
        print("Woof!")

fido = Dog("Fido")
fido.speak()

In this example, you have Fido, a dog, whom you have asked to speak. Fido goes about that in a fashion typical of dogs. The method, speak, therefore should be phrased like a request or command so that we mentally hear the echo of the actual phrase we might use with a real dog: “Fido, speak!”

However, real methods often get much more complicated.  First, we often have a lot more of them, even on a single object.  Second, we often find that we have many similar methods where we want to be able to distinguish between them.  To that end, method names should take the form of short, imperative sentences with the (programming) object the method is bound to as the (grammatical) object of the sentence.  In practice, the desire to keep the sentences as simple as possible tends to lead to using this progression of sentence forms:

  • verb (render)
  • verbNoun (renderPlot)
  • verbAdverb (renderGradually)
  • verbAdjectiveNoun (renderTopAxis)
  • verbPrepositionNoun (renderWithBorder)
  • verbPrepositionAdjectiveNoun (renderWithGreenBorder)

So, when faced with picking a name for a given method, I try to start at the top of this list, and then work my way down until I can find a method name which meets these criteria:

  • unambiguous in the context of this object
  • re-uses common words and phrases already used in related code
  • fits the pattern of other methods in the object and related code
  • uses language common in the real-world domain the code is about

Roughly of half the time, the first form works just fine: as it did for our dog example.  If that name would be ambiguous within that class, then adding a single word will often do the trick.  So, for example, if I have a render method on a class already, and I want to refactor it into multiple parts, I might add methods named renderAxis and renderPlot into which I’ll refactor the pieces of the original method.

In all of this, I always use fully and correctly spelled words.  The shorter, simpler and more common the words the better. That way, I take advantage of the common agreement on spelling to help prevent errors from dissimilar misspellings / abbreviations.  The only exception, is when an abbreviation is more common than the long-form version (e.g., HTML is far more common than hyper-text markup language).

✧✧✧

The crucial thing I try to keep in mind when choosing method names is that I’m writing for the sake of other humans, and that methods should be tiny, imperative sentences directed at the object containing the method.  The next reader of the code may be a new developer learning the code for the first time, a colleague who needs to make a bug fix in this area, or even myself a few months down the road when the details aren’t so fresh.  Following a definite pattern aimed at both keeping things simple, and keeping this clear goes a long way towards making your code its own documentation.

Leave a comment