Function Names: To Verb Or Not To Verb?

Wed 20 March 2013

I thoroughly enjoyed Brandon Rhodes’ PyCon talk, The Naming of Ducks, at which he presented and justified a panoply of Python naming best practices, far beyond the mere spelling rules of PEP 8. Among his recommendations was a common one: name your functions as if they were verbs so you know what they do. create_database, polish_silverware, televise_revolution—all make fine function names, or so goes the conventional wisdom.

Except that I’ve almost entirely dropped this practice in the last few years.

My motivation has been simple and pragmatic: verbing a function means obscuring what it returns. What does create_database return? A connection object? The name of the database? Nothing at all? So, instead, I’ve actually taken to nouning my functions, as I care much less about what they’re doing—that’s an implementation detail I’m happy to abstract away—than what they return, which is the immediate concern at the call site. This also fits nicely into my style, which tends toward the functional:

(csv_file_reader(f) for f in files_from_zip(zip_path))

Oddly enough, function-nouning forms a neat corollary to one of Brandon’s other guidelines: naming variables to make clear their types. I’m a big fan of this: name an arg connection_seq or connection_map, and callers can probably guess what kind of data structure to pass in without reading any docs. Combine this with function-nouning, and you make two things automatically clear:

  • The nature of the return value
  • The information that factors into the function’s result—care of the nicely-named args you pass in

Thus, the input is clear, and the output is clear. In fact, the only thing that’s left a mystery is the process by which the function effects the input-to-output transformation, and I contend that’s of secondary importance: most of the time, I’m content just to have the output I need and don’t bother about the implementation. Isn’t that the entire point of abstracting functions to begin with?

What do you think? To verb or not to verb? Perhaps a more imperative style changes the tradeoffs, or maybe there are practical advantages in verbing that I’m not thinking of.