Good Naming Things Is Hard

Author: Szymon Lipiński
Published at: 2017-01-23

Naming things is hard.

Usually when we are going to have a brand new kid, naming her/him takes a couple of months. The endless discussions, sleepless nights, all the lists of possibile combinations of letters. And all the effort just to achieve something that would sound nice to us. And only to us, as usually the grandparents of that brand new guy will not be happy with our choice.

The normal baby delivery date is quite far in the future, so usually we have lots of time to think about this name, and the possible problems the kid will have when naming like Donald Trump Otieno or like this:

delete from users

Naming Code Parts

When we are writing programs, we have to name many different things. We usually don’t have the opportunity to wait a couple of months, and discuss it forever. We need to name it now, and we need to do it fast.

The names are important because it is what we have when we read the code, and our brain wants to understand how this, and that is connected with each other, and with other things.

Just Too Long Names

If a name is too long it can be confusing, as it can be hard to remember. Take a look at this: SimpleBeanFactoryAwareAspectInstanceFactory, or this: InternalFrameInternalFrameTitlePaneInternalFrameTitlePaneMaximizeButtonWindowNotFocusedState. Well, 92 characters.

Nouns And Verbs

This is the most important thing I notice when working with lots of external libraries.

This is what we feel when we learn to speak as kids. This is what we learn at school. That the main word types are: Nouns and Verbs.

Nouns are basically for naming things.
Verbs are used for naming actions.

Here you can find more detailed explenation.

In programs we have some items, and some actions we do with those items. These parts are named differently in different languages, and for different ppurposes.

For Nouns we have:

For Verbs we have:

There is just one common pattern: Nouns is a thing, Verb is an action.

Why Bad Naming Hurts

This is something I described years ago. This way in one module HTMLParser you have a set of functions like:

getpos()
handle_data()
handle_starttag()
get_starttag_text()
handle_startendtag()

and in Python3 that didn’t change.

This way you remember function names, and have no idea how to write them.

The same situation is when you use a Noun as a function name like:

x.html()

Well, it should be either

x.html

or

x.to_html()

So either a Noun (as a property) or a Verb (as a function).

Final Notes

My main advise: just be consitent. Just use your language features, and don’t be afraid of the properties (if you have them).

The comments are disabled. If you want to write something to me, you can use e.g. Twitter.