Choose Your Words Wisely

One of my recent projects is taking over development of a Rails site to prepare it for a private beta and ultimately a public launch. Aside from the usual learning curve of understanding a large existing code base, I’ve been struggling more than I should with some of the terms chosen by the original developers. It reminds me yet again that naming is hard, but also that names are important.

Names are important because they instantly put your brain in a certain context. If you choose a poor name, while you may not have any trouble with it, new developers or your customers might find themselves nearly unable to understand your intention. Simply using a different word can avoid this problem entirely.

Consider the environment in which names exist, too. One of the core models in this project is Action, which turns out to be a very unfortunate name in a Rails project. It is natural to want to use a local variable called action in code that uses this model, but that gets messy because a method that processes a request in a Controller is also called an action. This code “worked around” the problem by using actions instead, but being plural, it makes my brain want to treat it as an array, when it usually isn’t.

Another term used in a lot of the partials is node. Again, considering the context, this is an unfortunate choice because when you talk about the DOM as a tree, it is made up of nodes. There is now an extra moment of thought when I see this term: is this talking about the application’s node or a DOM node?

Names are meant to ease comprehension of a system by putting it in familiar terms. As complexity increases, so does the importance of good naming. Spend the extra time settling on good names. It’s much harder to change them later, when they have spread throughout your code and your team’s vocabulary.