Thursday, March 12, 2009

Clean Code Clarification

There is a confusing edit result in Clean Code on page 25, referring to class names:

Class Names

Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb.

Read on its own, this makes it sound like I (or the editors) think "Manager", "Processor", "Data", and "Info" are verbs. Not so. Just an unwanted effect of editing. This is more disappointing than the neutering translation of my code example from Python to Java.

I became aware of the sloppy edit through a Sun forum where they were bashing the paragraph a bit, with good reason. Their arguments pro and con had little to do with my arguments, and I would have made clarification on the spot except they wanted me to to register and give a lot of personal information. Still, I suppose there should be a record somewhere of my correction.

Aside: if you want me to participate in your forum, don't make it a question of loyalty to your company or cause. I probably don't want you to have my phone number and home address and who-knows-what demographic information if that will take longer and have more lasting ramifications than my posting to your forum. And especially if it gives you spam powers.

That middle sentence is a reference back to page 21, where we talk about noise words and number suffixes. The problem with class names in the examples from the book is vague differentiation through noise words.

Most of the time, it is hard to tell the difference between several classes in a project which bear the names CustomerManager, CustomerGateway, and CustomerCoordinator, and CustomerHandler especially in the same project. What do the suffixes mean? Is a CustomerManager the class that creates and persists customers, or wouldn't that be the CustomerGateway following common naming practices? What is the Coordinator, and what does he coordinate with? And when do I use the Handler instead of the Manager? Words meaning "does something with" or "takes care of" don't quite cut it. Of these, 'gateway' has the most well-understood and widely prescribed meaning as a persistence mechanism. Differentiating between similar class names with noise-word suffixes is difficult. Much better if there is something in the name that clearly states its intent. Maybe one is a CustomerPersister, and another is a CustomerFactory and another is a TestCustomerGenerator.

Likewise, what is the difference between CustomerInfo, Customer, CustomerData, and CustomerObject? The additional words again provide differentiation, but without distinction. Is CustomerInfo the data-only persistent object I could use when I don't want to reify the Customer, or is it additional information about the customer relevant to an unstated aspect? Are CustomerData and CustomerInfo the same thing? Is one a message and another the Customer data formatted for a wire protocol? What is CustomerObject (and why put the word "object" in a class name?

I would rather the edit had not mixed the subject of verb-ness into a paragraph about poor noun choice. That was unfortunate.