I’ve got a shorter one this week. Partially, that’s because I was part way through a post before deciding to scrap it. Partially, it’s because I’ve written a few mid-week blurbs this week. Lastly, it’s because I don’t think I could stretch this article to be all that big. :)
Naming Functions
Generally, people are told to name methods and functions as verbs. If it’s not a verb, it’s a noun, and therefore an object (assuming it’s an OO language). In most cases, this is true, and, if you’re not sure whether to use the simple verb form or the form I’m about to mention, you should go with the verb form to be safe.
Past-Tense Verb/Adjective Form
What clued me into this naming convention was Python’s reversed function. You might say that it already is a verb, but I have two things to say to that:
- Normally, when naming your functions in their verb form, they’re in the “command” form. (i.e. run, filter, and print). They’re not past-tense.
- This is not actually a verb. It’s a word that is usually used as a past-tense verb that is being used as an adjective. This is English. Anything is possible here :)
If it helps you to think of it as a past-tense verb form rather than as an adjective, that’s fine, since it really only work works with past-tense verbs used as adjectives anyway (that I’ve been able to discover thus far).
When to Use This Form
The adjective form for naming functions and methods is not meant to be used a lot. It serves a specific purpose. It is meant for functions and methods take in an object (and this counts as taking in an object for methods) or multiple of the same type and return a new object of the same type (or possibly a similar one, like a subclass).
For instance, the reversed function in Python takes in a sequence and returns an iterator in reversed order. Another example is Python’s sorted. For an example of a method, you could look at combinedWith on my Weighted class. Weighted hold an object and an integer – or weight – and when two Weighted objects contain the same object and exist in the same “place” where duplicates of the object don’t make sense (i.e. two of the same face with different weights on a die in my dice roller library, where the weight represents how many copies of the face are on the die.) The combinedWith method takes in two Weighted objects (this and whatever is passed in) and returns a new Weighted object with the object held by both previous objects and a weight equal to the two previous ones combined.
The fact that it returns a new object is kind of key. If the Weighted class simply transformed the object in place, the function should be named combineWith. When looking at object1.combinedWith(object2), it is a phrase describing the result of running the method, but reading object1.combineWith(object2) comes across as telling object1 to combine itself with object2. The first one doesn’t really make sense as an in-place update to object1. If it was a function instead of a method, I’d use combined(object1, object2). combine works okay, but not quite as well IMO.
Outro
That’s about it. Remember, though, that this is applicable to pretty much any language. The Weighted class is actually a Java class – though I’m writing a Python version of the library it’s in at the same time as a chance to try out pair programming and teach my brother Python.
I ended up writing a little more than I expected, but it’s still less than usual.
| Reference: | Functions Named as Adjectives from our JCG partner Jacob Zimmerman at the Programming Ideas With Jake blog. |
