Hi! First of all I’d like to ask you a question – what’s your name? My name is Piotr and that is derived from the Greek Πετρος (Petros) meaning “stone”.  Next to me is sitting my friend – Michael. Michael is from the Hebrew name מִיכָאֵל (Mikha’el) meaning “who is like God?” (after this article he has new @mention on hipchat).  What do you think? Is it important how the parents call a baby? Does it determine his life? Some people assigns a deep meaning and character traits to the first name. But parents have own criteria to choose the baby’s name – is it beautiful enough? And I’d like to talk about those two criteriums – beautiful and meaningful. But not for baby, unless you think about your code like a baby.

There are only two hard things in Computer Science: cache invalidation and naming things.
~ Phil Karlton

Precise names for classes is notoriously difficult. Done right, it makes code more self-documenting and provides a vocabulary for reasoning about code at a higher level of abstraction. There are a couple of simple tips&tricks to make the names more readable:

• do not abbreviate,
• do not add any extra information (underscore, type)
• avoid single letter prefixes
• etc

But what if you already know and use those rules and you still want to improve naming in your code? I assume that you care, you’re not selfish and you think about elses when you write the code. You ask one of the most important question to yourself, during architecture implementation – how the fellow sitting next to you will behave while reading the code. Yes! You’ve done very first step to invent better names – you think about readability.

So, ask somebody else

Ask this fellow sitting next to you if he can say what the class or method is responsible for. If he does this fast and accurate then your name’s idea is exact. If not, describe him how the code works or should work and maybe you will figure out how to call this part. If you are working late, I mean really late, and there’s nobody else in the office then you should provide your own 24/7 help – the duck.

The duck technique is called that because one of the best programmer’s friend is a small bathroom duck. If you stuck or do not know what to do next, or do not know why the application behaves in a specific way, then it’s good to explain, step by step everything – the algorithm, proper behavior, meaning and the name purpose to somebody – the duck. I must admit that sometimes I treat my co-workers as ducks accidentally. They do the same with me. Have you ever been in this kind of situation when somebody comes to you, starts the sentence and find out the solution before you talk.

Single responsibility

And there the next problem comes, because you described what the class should do, but does it something more? Something what doesn’t fit to the name? If it does, remove this, move to another class, print and throw to the trash or burn. In this context a responsibility is considered to be one reason to change.

In the late 1990s Uncle Bob tried to merge this into a principle, which he called:The Single Responsibility Principle. But he also claims that the hardest thing in the principle is to define – what the change is. Some people think that the bug-fix is a change – “Certainly the code is not responsible for bug fixes or refactoring. Those things are the responsibility of the programmer, not of the program”, he answers. So, remember – almost every time the request for change comes from people and you don’t want to confuse those people, or yourself, by mixing together the code that many different people care about for different reasons.

Gather together the things that change for the same reasons. Separate those things that change for different reasons.
~Robert Martin (Uncle Bob)

The fact is, single responsibility class is easier to define and name. Single responsibility still doesn’t solve some problems.

Simple Superclass Name

Inheritance The Object Oriented Programming teaches us to create a general class with general purpose. How the general purpose can have a single responsibility? Well, that’s exactly why they invented the inheritance – to split the features between a group of similar objects.

The tricky thing is how to call the superclass. I’ve seen a lot of good examples for that – Product, User, JobConsumer and, of course, a lot of bad, Manager, Service, Handler, Helper. Do you see the difference. I have mentioned just a couple of names here and we can say something, at least something only about a few of them.

Qualified Subclass Name

Children in OOP are purposed to do the right job. Their responsibility is strictly defined, isn’t it? And of course the name should tell you a lot about this responsibility, but not too much.. Just imagine the parent class called Animal. We can define the purpose and what the children will do. But why, why the children have to be called LionAnimal, RhinoAnimal or FishAnimal? And what’s then? We should be consequence – CarpFishAnimal and YellowCarpFishAnimal.

My favorite example here is my own -ProductFactoryIteratorFactory. I must admit, the name was quite understandable until the first code review. Now I turn red when somebody’s talking about this class. At the end, calling children classes as Fish, Lion or Carp might be better than adding parent’s suffix.

Adding ‘Interface’ word

The same think is with adding suffixes and prefixes at all. I remember that time when you could find an underscore before private attribute like `private $_user`, or the small type letter like $sUsername. Totally unusable and unmaintainable especially now, when we replace ids, names etc. by value objects. Adding prefixes doesn’t add a value to the code, so why should these be added at all?

And what about suffix? The previous chapter was about that. I think the same issue is about adding the word interface at the end of interface name – interface ContextInterface. Isn’t this too much there? One of the finest example of naming I can find right now is the code of behat 3. By avoiding suffixes and prefixes, Everzet has created a great bunch of code. For instance:

Adding suffix Interface makes programmers lazy. They don’t thing about the names and create classes ex. Context implements ContextInterface.

But, some suffixes are better than others, because they have something to tell you. Classes which implement a particular design pattern might be given a name based on the well-known pattern name (e.g. FooFactory, FooFacade), and classes which directly model domain concepts can take their names from the problem domain. If the suffix helps with understanding the class architecture then it’s fine to tell about this, I think.

Avoid them

There is a bunch of words especially liked by programmers and dedicated by them to call the classes – Manager, Provider, Builder, Info, Helper, Util, Handler, Container, Service etc. My favorite in Symfony Framework will be always the Service. After all, everything becomes to be a Service and the developer feels proud of a good piece of design. Because he has services in the code.

Manager” has come to be a danger signal to me – warning of lack of thought on behalf of the application’s designer
~ Alan Green

So can you tell what those UserManager, CompanyManager and AddressManager do? No, because Manager is a very generic term that fits to anything you can do with your domain objects.

Once, I’ve read an article about using the Manager word in class name and there was an example with the UserManager. The job was allocating and freeing users from the heap. It would not manage the users but guard their birth and death. So maybe it should be called UserShepherd.

Is the name descriptive enough? Can you tell by looking at the name what the Class is supposed to do? Using words like “Manager”, “Service” or “Handler” in your class names can be considered too generic, but since a lot of programmers use them it also helps understanding what the class is for.

FILL IT WITH MEANING

Donald Knuth has written an article about Literate Programming in The Computer Journal in 1984. The main purpose is to create a piece of story in the code. If something doesn’t tell you a full story and isn’t readable enough then change it. The code should be readable like a book and should tell you a full story about the process, meaning and the purpose.

You will notice that every single word means something and if it doesn’t, it should be removed order not to obscure the general picture of the story. Back in 1983 Edward Tufte noticed the same thing with graphs. He displayed a new type of data graphic where he removed all unnecessary data from. This chart does this in a remarkably minimalist way. There’s absolutely zero non-data ink.

The exercise for today (Friday Dopamine Dump)

Get a piece of your own code which will have a fine business logic inside and tell loud a story. Don’t talk about the algorithm, don’t talk about the logic inside, just tell a story and then write it down. Ask your friend to read it and tell you where the story becomes a programmer’s language. And change this again, until the story will be full. After all, give this piece of code to your friend, wife or child and ask to describe what that does. If the explanation fits the business logic then the job is done.

* The action in controller will be the best for this exercise, I think.

Read more

[1]Naming classes how to avoid calling everything a Whatevermanager
[2]Naming JAVA classes without a Manager
[3]What names do you find yourself prepending/appending to classes regularly
[4]Whats the best approach to naming classes
[5]Donald Knuth – literate programming
[6]Uncle Bob – Single Responsibility Principle
[7]Edward Tufte’s “Slopegraphs”