Find the Right Naming — What Is a Good Class-Name

Every developer was at that point of searching desperately for the right naming for classes. If I have to guess, I would say I already spent several hours over the last years in finding good ones.

Isn’t it ridiculous to waste so much time for such a task? As everyone, including me, wants to write “THE” master piece of code or the next level of architecture, we should spend the time for coding, not for searching!

But enough is enough. I was tired of this and over the years I gained a small collection of names which I find really useful. The list is also inspired by articles or blog posts and are listed down below in the Source section.

How Much Time Should I Spend?

Seriously, is the name so important that you could not already start developing your task, module or whatever you are working on? 
No, it isn’t. This is why timeboxing is the key and should not use more than 10 minutes of your time. If I cannot find a name, I decide always to start with a placeholder and than it is easier to focus on the code again.

My placeholders by the way are super random. For example in my old team a task was to clean up old code and during the cleanup I discovered a class called OptimusPrime. I was so impressed by the creativity of this developer, that I still use this name if I cannot find the right naming.

Most of the time the name occurs to me during the development of the code I am working on, or a co-worker comes by and helps me out. Renaming classes in times of powerful IDEs like PHPStorm, VisualStudioCode or similar is not too hard.

How to create punchy namings?

Over the years my list already contains a nice collection of words. I was inspired by frameworks, communities like stackoverflow and of course other developers.

Working with other developers helped me a lot in understanding how the class should be named and it was also nice to see that even the most experienced developers have the same problems as everybody!

I mean, names for classes should be short and meaningful. To make it even more precise you can combine several words. It is easier to understand MultiMessageDispatcher than MessageService, because a MessageService could contain all or nothing.

Another bad example are helper classes. What is more descriptive? TemplateHelper or StringFormatter with concrete implementations?

Sometimes it is good to think about the names from a different angle. I always ask myself:

  • What naming makes my code better understandable for other developers?
  • Is the code reusable?
  • Did I separate the concerns?

Kent Beck, Autor of “Implementation Patterns” writes something suitable:

… A way out of this dilemma is picking a strong metaphor for the computation. With a metaphor in mind, even single words bring with them a rich web of associations, connections, and implications…

An example: The goal is to create something for handling excel files. A bad way would be to call it ExcelHandler or ExcelManager and it may has the methods read() and write(), but this is already too generic and creates room for misunderstanding the purpose of the class. The problem is now that concerns get mixed and the code probably ends up in chaos or logical errors. To avoid this the name could be more specific like XlsReader and XlsWriter. If we now also add a namespace for it, like Excel/XlsReader and Excel/XlsWriter we would already achieve a pretty good naming. Even further it is now easier to implement also a reader and writer for other programs like OpenOffice which maybe handle the files differently.

In my opinion there are words which are also strong and descriptive, like Composer, Converter and as so on and so forth, but they are already in use by most of the frameworks or plugins. This can cause confusion for other developers, due to different understanding or purposes and is a reason for me not to use them too much, but in the end every developer has to decide it on his own.

Explanations and Examples

During my research for this article I recognized that every developer has a different understanding for words and meanings. This is how I came up with the following explanation list of my understanding for some of the words.

Hydrator: Hydration is the act of populating an object from a set of data.
Writer/Reader: Is used for writing/reading operations e.g. ExcelWriter, PdfReader
Formatter:
ArrayFormatter, StringFormatter, JsonFormatter
Entity:
The lowest denominator for something (MessageEntity, ApiEntity…)
Resource/Presenter: Is used for decorating responses e.g. ArticleResource or UserPresenter
Repository: A central location in which data is stored and managed e.g. MySql/UserRepository, Mongo/ArticleRepository or Api/MessageRepository
Support: Is for me more part of the namespaces and identifies classes which are in addition to external libraries or to overwrite classes containing bugs which are not fixed e.g. /Support/FileReader/GenericFileReader or /Support/Laravel/AdvancedSessionServiceProvider
Extractor: Is used for extracting specific data from a given data source e.g. SpotifyArtistExtractor
Calculator: Is for mathematical operations e.g. RetailPriceCalculator or StockCalculator
Validator: Is for validation of requests or any other data source e.g. UserInsertRequestValidator
Job: Defines something server related e.g. ImportQueueJob
Events: Common in CRUD operations e.g. CreateEvent, UpdateEvent
Resolver: Kind of a mapper. Mapping Http-Requests to a Controller e.g. DnsResolver, HttpResolver or DependencyResolver
Factory: Is based on the FactoryPattern e.g. UserFactory

Summary

It is no secret that finding the right name is time consuming, but please don’t put too much effort in it, because your code will not last forever and the goal is to deliver a software which works and no user in the world cares about a fancy name and how much time you spent in searching for it.

tl:dr

  • Timeboxing (not more than 10 minutes)
  • Use short and meaningful words
  • Use random placeholder to start focusing on coding
  • A working code is the achievement, not a cool name
  • Separate concerns by using not generic class names

How do you handle this problem? What is your secret to start faster with coding? Please write a comment and let me know!

Sources