Engineering Blog

I’m a big fan of readable code. There are few things you can do that make your code more readable than using descriptive class and method names. The title of this post (other than my trademark Clean Code prefix) is intentionally poorly named. Would you have known what it was about without reading this paragraph? Maybe. Maybe not.

Nondescript names, much like nondescript blog post titles, have several problems. The first and most important problem is that you have no idea what the content is going to be. This problem is compounded for complex, non-composed methods. What do you think of this class:

public class AttributeBindingService {
  public void bind(Request request, Attribute attribute) {
    bindSharedFields(request, attribute);
    if(attribute.isCustom()) {
      bindCustomFields(request, attribute);
    } else {
      bindNonCustomFields(request, attribute);
    }
  }
}

I’d say this class snippet has mixed readability. The method is composed, which is a serious help. The class name and the public method name are fairly generic. The methods that are called are still a bit generic, but more descriptive.

Naming Rule 0: Compose your methods – it makes the rest of this shit easier.

If I said that in our app Attribute means user-defined field, and that BindingService means something that takes user provided values and shoves them onto an object, would that clarify your opinion?

Sure those terms make sense if you’ve memorized the Rally codebase glossary, but what about a new developer? Why not substitute a name like “UserDefinedField” for “Attribute” and “RequestBinder” for “BindingService”. AttributeBindingService probably makes perfect sense to anyone who’s been working with our codebase for a year. UserDefinedFieldRequestBinder probably makes sense to anyone who’s been working with our codebase for a month. How many possible meanings does Attribute have? Too many.

Naming Rule 1: Don’t use esoteric or ambiguous terms. Use names that will make sense, even to someone who has minimal familiarity with your codebase.

Next, what about the “bind” method? I think it’s fine, in context. It’s a name that’s inherited from an interface. Assuming that interface has well understood semantics, the generic name causes no problems AS LONG AS THE METHOD CONTENTS ARE READABLE. This method could pretty easily be rendered completely un-understandable by inlining some methods.

Naming Rule 2: Generic method names are OK as the public signature of a class as long as they conform to well-documented contracts.

I like it when my posts show up in the first page of google results for a fairly generic (if esoteric to our industry) term. This post never will.

Why not? The name mostly sucks. I say mostly because if you keep the prefix, it actually makes some sense. If you drop it, it’s probably in the bottom billion results.

In the Google index that is your brain, there are without a doubt important methods and/or classes you cannot find. Either the name is so ambiguous that it gets lost in the noise, or it’s so esoteric that it’s difficult to remember. The key is to name everything with enough context that it is discoverable. Googling for “names” won’t ever find this post. Tack on the “Clean Code” prefix and it’ll probably hit the first page of search results.

Naming Rule 3: Put your classes in discoverable packages. Put your methods in classes that make sense. Use the language of your domain. The best code you’ve ever written is worthless if no one can find it.