Good Naming Things Is Hard

published at 23 Jan, 2017 by Szymon LipiƄski tags: programming python java

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, the sleepless nights, all the lists of possible combinations of letters (just assume only letters for now). 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 family member 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 the 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 nine 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. Our brains want to understand how this and that are 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.

I know, this is named according to some naming schema used there, but come on, this will be even too hard for using an IDE to place that.

Nouns And Verbs

This is the most important thing I notice when I work 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 a more detailed explanation.

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 purposes.

For Nouns we have:

  • classes
  • objects
  • variables
  • fields
  • messages
  • attributes

For Verbs we have:

  • actions
  • functions
  • methods
  • subroutines

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

Why Bad Naming Hurts

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

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

Unfortunately Python3 doesn’t change that.

This way you remember all the 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()
x.as_html()

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

Final Notes

My main advice is: just be consistent. Just use your language features, and don’t be afraid of the properties (if you have them in you language like C# or Python. Java is a different world.).