Reversy Naming

I am always a dedicated fan of writing naturally readable code – by “naturally readable” I mean, one can read a line of code as if it were a sentence of English (or maybe other human languages). It’s believed that the practice encourages more self-explainable code, as the code reads more like a human-composed article, instead of some gibberish only recognizable by machine.

The practice recommends to name functions or variables following the word order of human language, for English that is, subjects come after verbs, and adjectives go before nouns that being modified. The samples below showcase how it guides naming in a program (please hold your opinions about the casing)

• append_to_list(lst, item). A function that appends an item to a list, which can read as “append to the list (specified by name lst) with the item”.
• register_service_notifier(func). A function that registers another function as a service notifier, which can read as “register a service notifier with the function func“.
• UserFollowersListView. The name of a web component which is a list view to display followers for a user.

It plays well and improves my developing experience most of the time, but there is no silver bullet, just like other practices or guidelines.Sometimes I found the readability even degrades. I kept skimming the lines and just couldn’t locate an item efficiently.

For a brief period, I thought it was caused by the verbosely long word sequence, since compared with shorter ones, they took more time to recognize. But then after some investigation, I realized it was not.

The true culprit is that, such “naturally readable” naming displaces the emphasis from the beginning of word sequence. The emphasis of a name is the words with highest level, usually the most general ones. For instance, append_to_list emphasizes on list, which is however placed at the rear of the name.

As human, at least for me, a name with its emphasis at the front is more recognizable than those doesn’t. When skimming through a screen of code, my sight focuses on token boundary like whitespaces, hopping from one to another. During which time, I will glimpse at one or two words next to the boundary, which, usually at the fore of a name, and subconsciously match them to what I am concerning.

The matching process itself, will speed up if I meet first the words at a leading position of the name / phrase. My mental model resolves a concept by first the general idea and then the descriptive details. This, however, goes to the opposite of most human languages, as far as I know, whose grammar puts general words after the modifiers.

And thus I come up with a new practice – the Reversy Naming, in order to accord with my mental model, which places the emphasis first in a name, and then goes the words at low-level. To illustrate, I apply the style to the three names above as an example

• append_to_list -> list_append
• register_service_notifier -> service_notifier_register
• UserFollowersListView -> ListViewUserFollowers

Probably wierd at first sight, but despite the inversed word order, they are not difficult to read. In fact, here comes several additional benefits.

Firstly, it conforms with the qualified syntax in most programming languages, which most people used to. A programming language with object-oriented paradigm usually supports a syntax like object.method. In Python I write things like list.append() for years, which is similar to aforementioned list_append, and I haven’t got any readability problem with it.

The next point is, the names will align well if they appears in consecutive lines. Consider there are many functions to operate a service, with “naturally readable” naming, we have

func RegisterServiceNotifier()
func UnregisterServiceNotifier()
func StartService()
func StopService()

It is not evident at a glance that these functions are for manipulating the same type, although they have a common word “Service” in the middle. But with Reversy Naming, we could have

func ServiceNotifierRegister()
func ServiceNotifierUnregister()
func ServiceStart()
func ServiceStop()

Now they share a common prefix, which indicates their affiliation, crystal and neat. If there’s a secondary emphasis, “Service -> Notifier” for instance, they will also align in a good manner.

I’ve also spotted similar naming rules in the wild, which supports Reversy Naming is an acceptable and recommended practice in some scenarios. For example, the Style Guide - Vue.js reads

Order of words in component names

Component names should start with the highest-level (often most general) words and end with descriptive modifying words.

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue

Since editors typically organize files alphabetically, all the important relationships between components are now evident at a glance.

Author: hsfzxjy.
Link: .
License: CC BY-NC-ND 4.0.
All rights reserved by the author.
Commercial use of this post in any form is NOT permitted.
Non-commercial use of this post should be attributed with this block of text.