Identifiers Reveal Intent

Maxim from the book SmalltalkBestPracticePatterns by KentBeck.

Bad identifier:

    quicksortVector(vector & v)    

Good identifier:

    sortVectorIntoAlphaOrder(vector & v)

Bad identifier:

    collateCustomerNames(vector & v)

Name services after what they do, and postpone the why until the point of usage. There's a great "a-ha" when you see "collatedCustomers = sortVectorAlphabetically(customers)" in the source; the "a-ha" is lacking when you see just "collatedCustomers = collateCustomerNames(customers)". If you want to abstract the "what", you should still have sortVectorAlphabetically for code reuse, and only redefine collateCustomerNames to not use it when change comes. -- PanuKalliokoski

---

Discussion

Bad identifier:

    sortVectorIntoAlphaOrder(vector & v)

Good identifier:

    collateCustomerNames(vector & v)

The first recants its own internal implementation. Hint: Courageous programmers expect to replace implementation at the drop of a hat. The second advertises why you should call the function, thus promoting reuse.

[RefactorMe: Please link to & from relevant pages.]

See IntentionRevealingSelector for the original name of the pattern. IntentionRevealingNames is more general.

I think the naming above violates ModelViewController unnecessarily. sortVect(v, cmp) is the model, collateCustomers(cust) is the view. -- PanuKalliokoski 13 May 2004

Now that I've reflected a little upon this, I've come to the conclusion that not only this violates ModelViewController, it is also a major hindrance of code reuse. People seem to confuse the how vs what question with what vs why. Almost everybody agrees that you should not name things after how they do something. But the above example does not say how the vector is sorted; it is not how, but what it does. And this is a good naming principle. Naming after the why (as the "good" identifier above) makes the service unusable elsewhere, because customer collating "owns" the name.

Rather, name services after what they do, and postpone the why until the point of usage. There's a great "a-ha" when you see this in the source: collatedCustomers = sortVectorAlphabetically(customers); the "a-ha" is lacking when you see just: collatedCustomers = collateCustomerNames(customers); if you want to abstract the "what", you should still have sortVectorAlphabetically for code reuse, and only redefine collateCustomerNames to not use it when change comes. -- PanuKalliokoski 20 Jul 2004

---

Proclaimed Daniel Longest from the mountaintops:

 > The following is probably silly but I've struggled with it. If I have a 
 > 'pure' container, in this case a vector, that will be of fixed size and
 > keep things in sorted order, is fixed_sorted_vector a reasonable name or
 > is this too long?

Name things after their intent. Do not name them after their implementation. "Ordered_Set" is the intent; "sorted_vector" is the implementation here.

Name things with complete words, not ugly acronyms, if they have a scope larger than a small block. Don't worry about typing them, or line length. Learn to copy-n-paste quickly, and I'd keep a right column limit of 130 characters these days.

 > What if the intent is to be a sorted vector? Is that still also the
 > implementation and ordered_set is preferable?

Of course you intend to implement. But you have to defend the name, outside the implementation, against the day when the implementation changes. It could change to a map<>, or a fixed_map<>. If the name reveals the intent (per Kent Beck's Smalltalk Best Practice Patterns) then those reading it know more about how they can use it. "InterfaceOrientedProgramming?" again.

Telling them the implementation hints at how they can abuse it.

--PhlIp

AreLongAndDescriptiveRelated

---

I worked on a C++ project where another programmer needed a new class to represent an object that had as its principal members a state (enabled or disabled) and an object name (plus a few domain-specific operations on them). Of all the names one could conceive for this class, I think "BoolStr?" is probably the worst, and naturally, what he chose...