Friday, September 5, 2008

Naming the Flag Object

So, you've decided to avoid the If Bug by using the Flag Object, but you can't seem to come up with a good name. Names should come from natural mappings not artificial ones. By that I mean the names of your objects should come from the customer's not the developers' vocabulary. Listen closely to what the customer says when she describes the story she wants implemented. When I asked my fictional customer,
"How are managers' pay calculated differently from regular employees' pay?"
she said,
"Managers and employees are paid based on different pay scales."

Now, I could have just listened to what she meant and gone about implementing a PayCalculator, but I listened closely to what she said and the words pay scale jumped out at me. That's how PayScale was born. Notice I chose a noun.

Avoid words which do not come from either the customer or the developer domains. "ER" words are the worst: Manager, Calculator, Helper etc.. These words hide the intent of your object, make it hard for other developers to trace its responsibility back to a user story, and lay the groundwork for the object to become large. How many small, cohesive, single responsibility FooManager classes have you ever seen?

When the customer comes to me later and says,
"We've changed the manger's pay scale to take into account how many employees each manager manages,"
I can go straight to the ManagerPayScale object and implement the changes instead of trying to figure out if the change is in the PayManager or EmployeePayCheckUtility or SuperPayRateHelper. The words manager and pay scale were written right in the feature request, so when I look in the paycheck package and see an object called ManagerPayScale chances are I won't have to look much further.

Names are very very important in development. Object names, variable names, and method names can make your code easy to read, intent revealing, and pleasant to work with. On the other hand, poor names hide intent, make code difficult to understand, and painful to maintain. Put effort into choosing your names. And when you get to the refactoring stage, reevaluate your names. Sometimes they make perfect sense when you first came up with them, but later, in the full context of the code, they don't. So change them. If you are not in a situation in which you get to pair program, show your names to other developers. The names might have made perfect sense to you, but others are going to have to maintain your code, so let them have some input.

Name your objects well and not only will other's enjoy maintaining your code, you'll have fewer bugs.


andrewsw said...

naming is huge. mschober and I spent *a lot* of time on naming. Names were constantly debated and changed as code was changed and roles shifted around.

It was effort well spent because the resulting code was much more clear. And you could tell when things were getting smelly because the old names wouldn't make sense anymore. .02

faithfracture said...

I always have a hard time coming up with good names for stuff. I always feel like the names I come up with are stupid and I wind up changing them usually later on so they make more sense. Fortunately there is the hand "find and replace", but I'd rather just get it to where I like it the first time.

andrewsw said...

@faithfracture: I don't think it's an issue of coming up with the right name right away. Unless you've fully designed the code from the first, you can't really know what something is going to become. Hence the mutability of names is a good thing. The name changes as the thing named changes over time. Eventually, as you move up the lower level names become more static and eventually may become like library names/api -- essentially unchangeable without serious pain. But by that time, the thing in question should be so well defined that the name is natural.

I think the history of names is interesting too. Looking over various revisions and watching the names of objects/classes change can provide insight in to the thought processes that were involved at the time.

very much .02