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. 🙂
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 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
combine works okay, but not quite as well IMO.
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.