Filina Consulting, Inc

Naming functions consistently

June 16th, 2015

I believe that in order to write readable and maintainable code, we must name our functions in a consistent way. What I noticed by reading a lot of code, especially frameworks, is that developers use too many different verbs when naming functions. It's even worse when the verbs are meaningless, such as handle, execute, do, match, etc. I even find them on their own. Just one word. What does the method do() do? It gets even worse. Many functions don't use a verb at all: any, pattern, with, except, etc. A function performs a task, meaning that it must use a verb.

The Problem

I understand, we're trying to save a few keystrokes and find clever words in our rich English vocabulary. Those keystrokes you save today will be the massive technical debt of tomorrow. Using a rich vocabulary makes the same action have two different names depending on context. Many of us are not even native English speakers, myself included. It moves us further from standardization, which is at the core of computer science.

The Need to Be Explicit

Why do we need to be explicit? Because we're writing code that has to be readable by future us and by other developers. Imagine listening to a speaker who uses mostly fancy words that you don't understand. Sure, we can look them up in the dictionary, but that would get tiresome very quickly and slow us down. It's the same when reading code. Even if it's well documented, we'd have to refer to the documentation every other statement. If we choose better function names, we could read the code without skipping a beat.

The Solution

I use a few simple patterns when naming my functions. It has served me well, making naming a very easy task. I reduced the method of communication to its most basic elements common to all applications in order to create a universal language (high five if you get the Stargate SG-1 reference).

set, get. I typically use those when I want to access or modify the state of an object. I wouldn't use get to fetch data from a database. In fact, I never use the verb fetch. Fetch and get are synonyms and are therefore redundant. Examples: getSql, setContent.

find. When I need to get data from a list using some sort of criteria, I'll use the find verb. This replaces both fetch and match in most frameworks. How do I differentiate between get and find? In my book, get doesn't take arguments, with the exception of getOffset for a collection. Examples: findRecords, findRoute.

create. Whenever I need a new object, usually from a factory, I use a straightforward create verb. Example: createResponse, createSqlQuery.

call. Instead of dispatch, handle and other variations, if my goal is to determine how to call a function and how to inject arguments, I'd use a call verb. It's not a verb that I use often, but it's a very straightforward one for this situation. Example: callController.

Edit: is, has. When you need to retrieve a boolean, it makes sense to use these two instead of get.

There are some additional verbs that I use on collections, such as add and remove. Besides those, I have very little need for anything else. Notice my pattern: I'm moving data from one place to another, instantiating and destroying objects, searching for data and calling functions or methods. Those are the basics of programming. I'm not "handling" stuff. I'm doing basic computing operations.

Final Thoughts

If I can't use one of those verbs, I start by checking whether my function is doing too much stuff or is doing something in a strange way. This is my trigger for code smell. These verbs lead me to cleaner architecture, to more testable code and to maintainable applications.

If you use too rich a vocabulary for verbs, then there's a high chance that your application parts are not decoupled or are doing too much magic. If you reduce everything to more basic functions, then that would also lead to shorter call chains (a function that calls a function that calls a function). Shorter call chains also means easier to trace and debug. The advantages keep piling up and the application complexity keeps dropping.

Happy function naming!

Comments

Cesar June 16th, 2015 Many times naming is contextual. For a class Dispatcher, a function dispatch makes more sense than call. It invokes a lot more significance.
In the same vein, fetch infers that you are going to retrieve data from resource type, while get does not invoke that same information.
Obviously, this is all information based on experience and cohesion.
Anna June 16th, 2015 I don't like fetch for that purpose. Public functions together form an API. I shouldn't have to know how things are stored internally to determine whether I should use a "fetch" or a "find" here. It should be a black box.

A dispatcher is merely calling a method or function based on some run-time state, so it makes sense to name it callController or something like that. Reducing everything to its most basic (information flow) elements makes things so much more clear.

My goal is to read code as fast as English with the ability to mentally visualize the state of my application without having to look anything up. This methodology gets me very close to that goal.
Cesar June 17th, 2015 What about a verb of the business logic? Shouldn't a model dog bark?
Anna June 17th, 2015 In an information system, I have never encountered a model that needed to bark. When I was building video games, I used methods such as playSound or playAnimation with a parameter.
David Hucklesby June 18th, 2015 That deserves a "like." It helps me bring more consistency to my JavaScript, as well as PHP.
Thank you, Anna.
Jake Carlson June 21st, 2015 I agree for the most part, but the verb 'handler' I use specifically to handle events in event-based architectures. I would argue that verb is most appropriate because the standard language 'handle some event' is widely used and accepted. No other verb in this context makes sense. I wouldn't use it outside an event context, though.
Anna June 25th, 2015 I guess it comes to personal choice. I see handle as a synonym of manage, which doesn't really mean anything specific. I'm curious what your implementation looks like. What arguments does the method take and what does it do internally?
Frank July 7th, 2015 Hi Anna,

Nice post! I was wondering how this comes together with DDD. I'm no expert there but from what I've seen, the vocabulary has no such things as `call`, `create` or sometimes even `get` or `set`.

I think Cesar's argument is a good one: sometimes things are in context. Take for example Eloquent's way of fetching related records: `User::find(1)->with('Post','Profile')`. To me this is well readable and concise. It has a method `with` but for me as a developer I know immediately what to do with it.

Thanks for your time!
Frank
Anna July 7th, 2015 You'd see that with methods that return $this, allowing you to chain calls in a succinct manner like that. I agree to have more variety in method names when it comes to specialized libraries as long as it uses familiar terms whenever possible. In this example, I like that it starts with a "find", which is one of the verbs I listed. Typically, you wouldn't have one class calling another using the method "with" and that's a good thing.

There should always be a point where you weigh how much easier life would be for another dev (or your future self) versus how many times he/she would have to consult the documentation to understand what's going on in the code.
Justin July 9th, 2015 Hello,

I completely agree with the ideas you've written about. I strongly feel that variables should be nouns and functions should be verbs. Then I hit the point I always struggle with.

I need a better verb for setting up complex data. For example, setScheduleID($id) should set the schedule id on the class. It may do other things like validating the id passed to it exists in the database, but it's primary function should be to set the schedule id.

Now the next step would be to have a function that builds out all of the data associated with that schedule. Essentially a shortcut method that takes the schedule id as an argument and then performs setScheduleID, get a list of all the appointments in the schedule, builds out a grid of times containing those appointments. Each of those is handled by its own functions but is called from within the core function.

I've tried build, construct, retrieve, several others, but none of them stick for me. I usually end up back at set. What would your convention be for that type of overall function?

Thank you!
Justin July 9th, 2015 After rereading my question, I overcomplicated it. A better example would be, I've already set the schedule id on an object and now I want to go retrieve the schedule's start and end dates from the database and store them as properties on the class. Using set or get bugs me because I'm retrieving data from a source and setting it on the class.

Any thoughts?
Anna July 10th, 2015 When you're struggling to find a good verb, think whether your design might be the issue. For example, you're mixing a model class with a data access class. In most frameworks, you'll find that these things are separate. There is a very good reason to keep these separate which are listed here: https://en.wikipedia.org/wiki/Data_access_object

For example, you can have a ScheduleRepository object on which you call "findById", which will then return a Schedule object.

Stricter naming conventions force me to think about my design and improve my architecture.
Justin July 10th, 2015 Thanks for the quick response. I generally do maintain them as completely separate objects, that's why I realized my first example was a poor one. The second one is a more realistic case.

I consider "get" to be the verb for returning a property on a class. "set" to be the verb for setting a property based on an argument. But I don't have a good one for retrieve from the database because that's getting it from some place and then setting it. Is that where you'd use find, because you're finding it in the database?
Anna July 11th, 2015 Yes, find would be an appropriate verb for getting things from a database or even a list (like `$router->findByName($routeName)`). In your case, you'd use `$schedule = $scheduleRepository->findById($id)`. The idea would be to get a completely new Schedule object from the repository, not merge data into the one on which you just set the id.

Regarding get and set, I use magic getter and setters with optional methods when I need extra logic, such as returning a placeholder image whenever I encounter a null. Here's what a magic getter looks like:
```
public function __get($property)
{
$getter = 'get'.preg_replace_callback('/(?:^|_)(.?)/', function($matches) {
return strtoupper($matches[1]);
}, $property);

if (method_exists($this, $getter)) {
return $this->{$getter}();
}

if (property_exists($this, $property)) {
return $this->$property;
}

throw new \Exception("Property {$property} does not exist.");
}
```

So calling $object->image_url would first try a method named getImageUrl(), then a property $this->image_url and if all fails throw an exception.
Liem Le December 15th, 2016 Thanks Anna, this really a nice post. It help me a lot in naming my method.


This page is protected by reCAPTCHA and the Google
Privacy Policy and Terms of Service apply.

Phone: +1 514-918-7866 | E-mail: me@afilina.com