Hi, my name is ___

Photo of 4 iPhones saying helloby Daniel Romero on Unsplash

One of our most frequent tasks as programmers is assigning names.  It’s hard to go an hour without coming up with a name for a class, a method, or a variable.  But naming things is hard for at least two reasons:

  1. The exact purpose of an item might be not be clear until you’ve written its body or used it in context.  I often use a clearly inappropriate placeholder that will force me to replace it once I have a good name.
  2. Picking appropriate words is tough.  It can be hard to spend time selecting the right word when you’re focused on writing logic, but often the work of naming will help clarify that logic’s organization.

Here are some suggestions for naming rules, born from recent experiences.

Rule: reflect the usage and context

A name is the first and most important way a reader will determine what something does, and whether it’s the appropriate something to use.

If a class has a very specific context in which it’s useful, reflect that context in the name or its containing package.  On the other hand, think forward to future uses of a class, and don’t unnecessarily restrict it to Foos by calling it FooEngine when it might also be useful for Bars.

Rule: influence the named object’s scope

Names can act as a valuable indicator that the scope of a class or method has grown too big.  If a good name doesn’t seem to comprise the full functionality any more, or conversely the functionality is suggesting a name that involves too many steps, then consider factoring out some of that functionality.

A class named SearchEngine that’s also used to retrieve user configured paths needs to be refactored into at least two classes.  A method named ValidateUpdateNotify (or more problematically, Process) should actually be three separate methods.

Rule: name length is inversely proportional to usage frequency

The more frequently a name will be used, the shorter it can and should be.  The length and obscurity of names impacts how other developers use the named objects.  In the following comparison, split is idiomatic, familiar, easy to read, and easy to remember; componentsSeparatedByString is much less so:

# JavaScript, Ruby, Python
'a b c'.split(' ')

# Objective C
[@"a b c" componentsSeparatedByString:@" "]

Apple’s very long method names such as tableView:accessoryButtonTappedForRowWithIndexPath: have a clear benefit of being self-documenting and are appropriate for less frequently used API classes.  But for the more common classes and methods in a language, API, or project, they add an unnecessary burden to the developer.

Rule: unique names are searchable names

If you ever need to refactor a widely used method or search the git commit history for the introduction of a variable, you’ll be grateful if the name is unique.  For example, name a class PurchaseOrder or JobOrder rather than Order, which will easily be confused with sorting or other meanings for the word.

Rule: alphanumeric names are Googleable names

If your name is as popular as "C#", search engines will return good results; otherwise, avoid special symbols in public names since they tend to be chomped from queries.  This rule becomes doubly important if the name is not otherwise unique. For example, the JavaScript library jQueryMX (now rechristened Can.js) borrowed the "$" prefix from jQuery, and named its most important classes $.Model and $.Controller.  Try searching Google or jQuery’s own forums for "$.Model", and the results are next to useless.  Obstructing your users’ most important tools for gathering and sharing information about your framework is a sure way to consign it to oblivion.

Rule: rename when necessary

In many cases, it’s hard to get a name right the first time, particularly when requirements or architecture change.  As a project evolves, make sure to keep the above rules in mind and rename your classes and methods when their roles change.  Don’t let a name rot into inaccuracy.

Read more

The subject of naming has been a popular one over the years.  Here are some worthwhile posts:

Can (and Should) Everyone Learn to Program?

Photo by Luca Bravo on Unsplash

Fair warning: The following article is long, rambly, and contains no code. It does, however, contain some rumination on the idea that everyone can and should learn to program. Want to put your two cents in on the topic? Skip straight to the comments – I look forward to reading what you think.

So, I was just thinking, it would be really great if you could come present to my CS class – talk about programming in general, as a job, that kind of thing.

Recently an old university friend of mine, now a Math and Physics teacher, was tasked by his administration with teaching computer science to his highschool students.

His experience with CS being limited to the half a dozen or so courses he took years ago to fill out the minor requirements of his degree, and the prescribed curriculum being heavy on the history and ethics of computing and light on actual programming content, he’s been struggling with how best to present the essential concepts in a way that would appeal to typically lethargic teenagers.

They really need to be taking the work home, exploring the concepts on their own – there’s only so much we can do in an hour a day. There’s all sorts of resources out there – I just need a way to spark some excitement about programming in them. Maybe having a ‘real’ programmer come in would be helpful?

I agreed, and began to prepare my presentation. While the Way of the Programmer had been known to me since the childhood discovery of the QBasic interpreter in DOS, it wasn’t until highschool that I truly took the first steps on this Path to Enlightenment – thanks in large part to a wise teacher/mentor, as per the trope. Doing my part to introduce some young minds to this sometimes frustrating, but often rewarding discipline would be a Good Deed®.

I had an additional ulterior motive, however. I had often seen espoused – mostly in various communities populated primarily by programmers (such as Hacker News) – the opinion that programming was/is the new literacy; that is, a basic element of education that everyone can and should learn. Both they and my teacher friend had noted the ever-expanding collection of sites dedicated to teaching programming: Code Academy, Starter League, Code.org, amongst many others. They seemed certain that not only could anyone learn programming, but everyone should learn programming.

I wondered if anyone not already committed to our discipline felt the same way – particularly the students who should apparently be learning their if, while, foreach alongside their ABCs.

Here was a chance to find out.

(more…)