Naming things well is a huge deal.  It’s hard and it should be hard. Poorly named things can mislead/confuse people, slow down velocity, and cause poor separation of concerns in design/implementation.  On the other hand, well named things will allow others to correctly understand the function and use of an object, as well as encourage correctly placing new functionality in the proper object or layer.

SomethingManager

I have been guilty of all of these, and have had to refactor my mistakes out of code.  The worst offender in lazy naming is the “SomethingManager”.  It sounds like it should mean something, but in practice it’s overused to the point of obscurity.

Alan Green rails against the meaninglessness of SomethingManager and makes several good points:

How many classes do you come across named ‘SomethingManager’? 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’s a pool of URLs, manipulates URLs or audits the use of them. All the name tells you is that this is not a URL, but it does somehow work with them. On the other hand, the name “UrlBuilder” gives a much better picture of what the class does.

This lazy way of naming leads to all kinds of confusion.  Usually people use “SomethingManager” because they have not fully defined what this thing is supposed to do and it winds up being a bucket for things that don’t really fit somewhere else.   Avoid SomethingManager in favor of something more explicit, like SomethingBuilder, SomethingPool, SomethingSupervisor, SomethingTransformer, SomethingShepherd/SomethingWrangler, SomethingGatekeeper, or SomethingUtilities.

A sibling of the SomethingManager is the SomethingDAO.  Often we are not sure if this should be a factory of the “Something” or a set of utility classes for the something, or the only access point for the something from a datasource.  Sometimes it’a all of those things.  Be careful with the separation of concerns and be consistent in your usage of the SomethingDAO suffix.

Another sibling is SomethingEngine.  Sounds good at first, but what does it really do?  Does it produce the Something or consumer the Something or maybe refine the Something?  Engine is a word overused to the point of being more confusing than useful.  Perhaps you need to better define this idea before you just call it an engine.

Redundant Naming

Adding the word “object” to the name of a coded object adds nothing.  You already know it’s an object, so adding it is meaningless and just adds extra keystrokes every time you want to use that object.  Sometimes you may use more vague names for an abstract class or parent class, but in general more specific is better.  The same with methods.  Avoid the overly generic “HandleOutput”.  That tells me you’re not sure what this is supposed to do.

Another example of wasted characters is putting the type of object in the name, when it’s already understood from context.  Like with spring or blueprint xml definitions.  You know these are blueprint definitions because of their location, context, and content, so to have the name “blueprint-cnf.xml” is meaningless once you move beyond the “Hello World!” tutorial.  This name shows up in monitoring & admin tools and you will have 20-30 camel contexts all named the same thing for the first 10-15 characters.  It’s like trying to find the plumber in a room full of guys with name tags that all say “Member”.

Also adding a number to an object or method doesn’t tell you anything other than it’s different.  You have to read the code to see how it’s different.  Using a method signature such as open(Node node) vs open(String xml) is explicit and useful.  But open1() vs open2() is meaningless.

Using Common Pattern or Paradigm Names Differently

Using the words “view” and “model” and “controller” in a context that is not the MVC paradigm can create confusion.  Or using any of the common Design Pattern names (singleton, decorator, observer, etc.) in a way inconsistent with the commonly understood pattern is also a way to confuse and mislead fellow technologists.  Another good place to look at naming is in Enterprise Integration Pattern names.  Using familiar names in an unusual or just different way leads to confusion.

A good idea would be to read through these paradigms and their naming.  Using these patterns is also an excellent choice for design implementations in addition to naming.  You would be wise to adopt these patterns and use the names for them consistently.

Naming Sins to Avoid

• SomethingManager suffix
• SomethingObject suffix
• TheSomething prefix
• ASomething prefix
• Misusing a common pattern name
• profanity anywhere

Method/Function Naming verbNoun pattern

A good pattern to follow for naming a function or object method is verbNoun, such as getNode(), or findNodes(), transformMember(), isDirty().  These use the verbNoun pattern and some also reference what they return such as a node, a set of nodes, or transformed member.  In the case of a boolean, specifying the condition being tested with “is” helps make it clear what true/false means.  Instead of being confused about cleaned() = true, does true mean it’s been cleaned or does true mean it should be cleaned?

Naming Considerations

Giving your classes and objects good, descriptive names isn’t easy. Steve McConnell provides a few helpful guidelines for routine naming in Code Complete:

1. 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.
2. Avoid meaningless, vague, or wishy-washy verbs – Like UrlManager, or HandleOutput(), or PerformServices(). 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.
3. Don’t differentiate routine names solely by number – I include this only for completeness. If you ever find yourself writing OutputUser1()and OutputUser2(), God help you. And God help the team you work with.
4. 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.
5. For functions, try using a description of the return value – An easy, straightforward rule. Some examples are printer.IsReady(), pen.CurrentColor(), etcetera.
6. Use opposites precisely – For every Open(), there should be a Close(); for every Insert(), a Delete(); for every Start(), a Stop().
7. Establish conventions for common operations – This is best illustrated with an example, and McConnell provides an excellent one:

8. employee.id.Get()
   dependent.GetId()
   supervisor()
   candidate.id()

Now how do I get an Id again?

Summary

If you have never been to Jeff Atwood’s site you should be sure to read his wisdom.  On naming things  Jeff Atwood at CodingHorror.com has this to say:

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.

Putting in the time to name things or rename things correctly demonstrates professionalism and maturity in software development.  This is one of the qualities that separates the coding hack from the professional developer.  It’s about craftsmanship and pride in a job well done. 

Design Philosophy

Generally, if a software package is hard to install, configure, or to otherwise use, I avoid it. If it’s hard to maintain or even tell what’s happening when its running I avoid it.  I’m not being arrogant, I’ve just done it wrong more than once and had to live with it and/or fix it.  I’m speaking from experience; I’ve used a lot of overly complex systems.  I’ll even confess that I’ve built some overly complex (awful) systems myself and it didn’t end well. That’s why I take such a strong view against complexity. In short, I actively avoid baroque needlessly complex systems and strive for simplicity.  I see complexity as a sign of weakness in design and implementation.

Simplicity Equals Elegance

Simple software design often ensures success (both short term and long term), but it also helps to maintain the sanity of those who use that software. How much time have you spent wrestling to get a web server, application server, or database server up and running, and configured properly, for example? Or trying to solve an issue in a production system because you can’t tell what is happening and where it’s going wrong?  It’s no accident that the main goal of Java EE 6 was to simplify Java EE development and deployment. Simplicity is also why thousands of developers have moved to other languages and environments such as Ruby to build web applications.

But when you need to connect more than one computer together, and arrange to have software communicate and coordinate activities between them, a certain level of complexity is unavoidable. For instance, a network stack consists of many low-level software components coordinating bits of data transmitted by fluctuations of electricity over a wire and though a network interface card. There’s very little simple about that, even at a high level. But computer science offers solutions to help here as well.

Abstraction or “Just wrap it!”

As a user or developer of network software, life is relatively simple today because operating systems and software libraries provide a nice facade to interact with. Behind these facades is typically a level of complexity most of us are not interested in dealing with, but thanks to clever design you may never have to. This is called abstraction, where you gain the ability to treat an entire system of seething complexity as a simple box in a diagram, or entity in your mind. Not everyone has the ability to abstract to the level required to deal with such things. Just as the most famous artists have used it to amaze us with their work, the best computer scientists use it to solve complex problems with (sometimes only apparent) simplicity. This is what computer scientists often refer to as elegance. 

With this in mind I would suggest that the reciprocal idea is true too.

Elegance Equals Simplicity

Simple and elegant software design should go beyond just the code that makes the system work, it should extend to the user interface (or API) as well. This may be obvious for applications with a graphical interface, for which there are ample guidelines to good design, but it also applies to applications with more abstract interfaces: the tools and systems that we use to develop and deploy other software. For instance, why has FTP lasted so long in a world where constant software upgrades are a fact of life? Because it just works, out of the box. This is how all software should be. Don’t make installation, configuration, and usage an afterthought.

Turn your design inside out

A good internal design should be turned inside out, and it’s usage should be as elegant as it’s inner workings. If it’s pretty on the inside, it should at least be as pretty on outside. The inverse is true for those whose focus may be on the outside (i.e. graphic artists). If you’re a UI designer and also a programmer, try not to sacrifice the elegance of your software’s internal design for the sake of quickly iterating the UI. I’ve seen far too many prototypes (with hacked together code that was never meant to survive) become the actual product because of time constraints. Again, I speak from experience; this is another software crime I’m guilty of.

How do I tell if it’s “Elegant”?

Here are some questions to ask/answer yourself:

• Does it work? I’d be hard-pushed to call software “elegant” if it didn’t work.
• Is it easy to understand? Lots of the following factors can really be summarized by this one: if I can’t understand the code, it’s not elegant.
• Is it efficient? A bubble sort is just not elegant, because there are much more efficient algorithms. If a cunning algorithmic trick can drastically reduce the runtime, using that trick contributes to making the code elegant, especially if it is still easy to understand.
• Does it have short functions? – Long functions (more that 25 lines of code) make the code hard to follow. If I can’t see the whole function on one screen in my editor, it’s too long. Ideally, a function should be really short, less than 5 lines.
• Does it have consistent descriptive naming? – Short functions are all very well, but if functions are called foo, abc, or wrt_lng_dt, it can still be hard to understand the code. Of course, this applies to packages, classes, functions, and even APIs.
• Is there a clear division of responsibility? Is it clear which function or class is responsible for any given task or aspect of the design. Not only that, but a class or function should not have too many responsibilities — a class or function should have just one responsibility.
• Is there high cohesion? Cohesion is a measure of how closely related the data items and functions in a class or module are to each other. This is tightly tied in to division of responsibility — if a function is responsible for calculating primes and managing network connections, then it has low cohesion, and a poor division of responsibility.
• Is there low coupling? Classes and modules should not have have unnecessary dependencies between them. If a change to the internals of one class or function requires a change to apparently unrelated code elsewhere, there is needless coupling. This is also related to the division of responsibility, and excessive coupling can be a sign of too many classes, modules or functions sharing a single responsibility.
• Is there appropriate use of Object Oriented Design and other techniques? It is not always appropriate to encapsulate something in a class — sometimes a simple function will suffice, and sometimes other techniques are more appropriate. This is also related to the division of responsibilities, but it goes beyond that — is this code structure the most appropriate for handling this particular responsibility? Language idioms come into play here: is it more appropriate to use STL-style std::sort on an iterator interface, or does it make more sense to provide a sort member function? Can the algorithm be expressed in a functional way, or is an imperative style more appropriate?  Are we “coding in XML” or “putting configuration in code”?
• Is there minimal code? Code should be short and to-the-point. Overly-long code can be the consequence of doing things at too low a level, and doing byte-shuffling rather than using a high-level sort algorithm. It can also be the consequence of too many levels of indirection — if a function does nothing except call one other function, it’s getting in the way. Sometimes this can be at odds with good naming — a well-named function with a clear responsibility just happens to be able to delegate to a generic function, for example — but there’s obviously a trade-off. Minimal code is also related to duplication — if two blocks of code do the same thing, one of them should be eliminated.

This is not an exhaustive list, but will help understand the concept of simple and elegant is software design and development.