I Shall Call It.. SomethingManager
Alan Green rails against the meaninglessness of SomethingManager
:
How many classes do you come across namedSomethingManager
? Any decent sized commercial system seems to have plenty –SessionManager
,ConnectionManager
,PolicyManager
,QueueManager
,UrlManager
,ConfigurationManager
, or even, sadly,EJBManager
.A quick look at the dictionary entry for "manager" and "manage" gives at least ten different meanings - from "to make and keep compliant" through to "to achieve one's purpose". I remember one day when the receptionist briefly retitled herself as Switchboard Manager. The common semantic to all these definitions seem to be a vague "looks after stuff".
This imprecision makes Manager a bad word to use in naming classes. For instance, take a class named
UrlManager
– you cannot tell whether it pool URLs, manipulates URLs or audits the use of them. All the name tells you is that this class does something with URLs. On the other hand, the nameUrlBuilder
provides a much clearer picture of what the class does.In the Java world, the Manager suffix is thrown around a lot. Almost anywhere you have a class that is responsible in any way for other objects, it automatically earns the Manager label.
There's nothing more ambiguous than a SomethingManager
. Avoid this word. Alan proposes a few alternatives in his blog post that might be helpful in narrowing down what your class actually does.
Giving your classes and objects good, descriptive names isn't easy. Steve McConnell provides a few helpful guidelines for routine naming in Code Complete:
- Describe everything the routine does
And we mean literally everything. If that makes the name ridiculously long, the name isn't the problem. Your routine is.
- Avoid meaningless, vague, or wishy-washy verbs
LikeUrlManager
, orHandleOutput()
, orPerformServices()
. Be specific. What does it do? If you can't answer that question succinctly, it may be time to refactor the code until you can.
- Don't differentiate routine names solely by number
I include this only for completeness. If you ever find yourself writingOutputUser1()
andOutputUser2()
, God help you. And God help the team you work with.
- Make names as long as necessary
According to McConnell, the optimum name length for a variable is 9 to 15 characters; routines tend to be more complex and therefore deserve longer names. Make your names as long as they need to be in order to make them understandable.
- For functions, try using a description of the return value
An easy, straightforward rule. Some examples areprinter.IsReady()
,pen.CurrentColor()
, etcetera.
- Use opposites precisely
For everyOpen()
, there should be aClose()
; for everyInsert()
, aDelete()
; for everyStart()
, aStop()
.
- Establish conventions for common operations
This is best illustrated with an example, and McConnell provides an excellent one:employee.id.Get() dependent.GetId() supervisor() candidate.id()
Now how do I get an Id again?
I'd say renaming classes and variables is one of my most frequent refactoring activities. Creating good names is hard, but it should be hard, because a great name captures essential meaning in just one or two words
It's difficult to tell what something should be named until you're completely finished writing it. And like most code, it's never quite done, so the name may change over time. Succinct, descriptive variable, object, and function names can make the difference between Daily WTF code and… well, code you'd actually want to work on.