The other day I had a small discussion on one of my open-source projects, in this case Flysystem. It was about the smallest thing ever, the name of a method. A method name that was suggested to replace another method name just didn’t feel right to me. It made me wonder why. I came to the conclusion: Using lingo in code should be avoided.
What is coding lingo?
What I mean with “coding lingo” is hip and themes names for methods, functions and other code related things. For example, a Hulk-themes caching library where you’d have to do $hulk->smash($item) to delete a cache file. It looks fun, but naming things like this is an anti-pattern.
What’s going on?
Naming things. Every developer does this every day. You’ve come up with a function, class, trait, interface, a solution. All it needs is a name. As have many others, I’ve come to the conclusion this is nothing short of an art-form. Naming things is extremely hard and should not be taken lightly.
There are some packages out there that create their own lingo, call it “slang” if you will. A style of naming things which makes it stand out of the crowd and gives subtext which may, or may not, appeal to other developers. While there’s no doubt about lingo being “cool” and “hip”, I find myself more and more moving away from doing this. I’ve come up with a number of reasons why.
Go for clarity
Naming things is hard. Clarity is one of the factors that helps other developers out when trying to understand your API. The sooner they understand one part, the sooner they’ll move to the next and be up and running in no time. While we, as developers, are freakishly close to being super-human, we still haven’t mastered the power of the “eternal attention span”. Understanding a concept can only take up so much of our time before we move on and learn something else. Avoiding the use of lingo in your code will speed up understanding and lets your community cover more ground in the same time.
Not everybody is English
While many people that code have a perfect understanding of the English language, others might not. Like myself, there are loads of developers where English isn’t their first language. Lingo mostly comes from sub-cultures or social groups: these groups might not be accessible to everyone. Assumption is the mother off all evil. Don’t assume everyone has the same frame of reference.
Because not everyone is a native English speaker, when using it, you’re putting up a boundary. An important step in creating a community around your product (or package) is to make them feel included. While other boundaries, like high coding standards, help the community out, this doesn’t bring anything valuable to the table.
While a lingo can certainly also help for the group to create a sense of belonging, it does make it harder to enter the group in the first place. Some developers have a limited vocabulary to begin with. You can help them out by making it easier to understand what’s going on.
Lingo is limiting
Lingo IS NOT a full language. Depending on which style you choose, the pool of options to name things gets smaller and smaller. Projects tend to grow and with it the amount of things to name. Because of the limited vocabulary of any given lingo, naming a function or class will become increasingly difficult. A perfect fit is less likely to be found. As a result your API will become less understandable. This, again, will raise the level of entry needed to get started.
Look up any word on the Urban Dictionary. It’s more than likely every word in there has more than 3 definitions or use cases. By using lingo you increase the chance of getting conflicting names.
Multi lingo madness
The PHP world (which is my main point of reference) is becoming more and more package-oriented. Packages are combined to create awesome stuff. Better abstractions are made to ease the use of complex tools. On a project a developer might pull in 10 or more packages to get a running start. Having to learn, understand and maintain the understanding of lingoes from 10 different packages is just insane. Even if the packages individually have a consistent naming convention, the lingo will most likely never match with all other packages out there. The final result for the end-user will be a big bowl of “slang”-soup. A hard to understand, big pile of brain farts.
Code doesn’t have to be cool
It has to be usable and well designed. That is the metric code should be judged by. Of course code can be so well designed that it’s cool, but “acting cool” is not the way to go.
API design is communication
Code is meant to be used, by you and by others. Working in teams requires a good deal of communication. Time will be lost when you’re not using names which are descriptive and expressive. Your co-workers will need to look up anything they don’t understand, this time can be greatly reduced by spending a little more time to think about what things are called. It’s an investment in the future of the package/project.
Good API design will help people to better understand what needs to be done to go from A to B. When maintaining a project this will decrease the amount of support you’ll need to provide to the community, allowing you to free more time to improve and innovate.
So what do I think we should do?
When you’re naming things, there are a couple of things you can take into account. Some will help you out, others will prevent you from even having to name things yourself.
1. Use common names in your domain.
In some way every domain already has it’s own lingo. Whether you’re writing an EventEmitter, Database Abstraction Layer or translating real world interactions to their digital counterparts, chances are standard terminologies already exist. Using these terms has two major benefits.
- You don’t have to think about how to name something. It’s already named for you!
- People have a bigger chance of instantly knowing what you mean, you’ll spend less time explaining yourself.
2. Don’t be too abstract, be concrete.
As developers, we like design patterns. It’s in our nature to want to make things simple. Sometimes we’ll over-abstract when we’re in the pursuit of simplicity. A mistake I’ve made more than once is to use a too generic term to describe classes.
An EventEmitter, for instance, has a method to connect a listener to an event name. This could lead us to think “connect” might be a good name for this function. But it’s still not describing what the intention of the method is. Using something like “listenTo”, or “addListener” even, makes it very clear. We’re listening to something, or adding a listener. Both leave very little up to interpretation.
3. Don’t abbreviate.
Abbreviations are a very common sight in our field. The main argument to use them is because you’ll end up writing less code. While this is somewhat valid when you’re creating new stuff, it doesn’t apply to all the other work we do. Not only are we creating, we’re reviewing, re-understanding, re-defining problems. Using abbreviations makes it harder to understand what’s going on. While naming a function “calcProgDest” might have seemed like a great solution at one time, Future You won’t be happy with it at all. Scanning documents and code becomes increasingly difficult with more abbreviations.
4. Use names that make sense.
The human mind has two parts where memories are stored. One it in the middle of the brain, the other sits in the back. The middle of your brain is used for new memories. Things we’ve encountered but have yet to make sense of. You can see this as a queue which is processed to store memories in the long term memory. Memories at the back of your mind are things we’ve made sense of. When we’re dealing with the memories from the middle part, we’re trying to make them logical. This is done by comparing them to existing memories, or new experiences which help the brain to make sense of things. Something with a common name, that people can easily relate to, is easier to memorise because of this. Hint: lingo is not what you’ll want to go for.
Stay away from a “theme”.
Themes are the worst, just the worst. Imagine an Rocket themed event package. Emitting an event would be done by “->launch()”, stopping propagation by “->houstonWeHaveAProblem()”. I think I’ve made my point.
Naming things is hard enough as it is, so is understanding all the technologies we’re introduced to every day. People shouldn’t have to question what the intention of a piece of code is. It should be clear from the context as much as possible. The API is the UX for coders. Take good care of it, don’t mess it up with lingo.
PS: A Case For Package/Framework Names
This is far less of a concern. Naming every package the same is not only impossible in PHP due to class name collision. It’s like naming all your kids “Jimmy”, a bit silly.