Both try to enumerate house chores and convey the same meaning, but the one on the right does it in a neater, more elegant and predictable way. In that particular example, all entries are composed of a verb in the infinitive form and a noun or expression acting as the object of that action. You don’t need to think about it at all, but after reading a couple of them, your brain actually expects the next list item to be built using the same structure. Aesthetics aside, pretty much like a hard drive that relies on the principle of locality to read data ahead of time, knowing something about what comes next usually makes for faster skimming and quicker understanding of the message being read. This is called syntactic parallelism and is one of the key concepts you should take away from this article. Make a Memory out of it.

Objects and Collections

Developers face a very common naming tradeoff when they have to deal with both single objects and their collections in the same coding context:

On the one hand, you can opt for briefer, more concise names, using the classic singular/plural forms, such as account and accounts . This will shorten lines of code and minimize line-breaking, improving block readability and reducing overall code verbosity. Alternatively, you may choose longer, more explicit differentiations, like accountObject and accountCollection , which in turn will favor clarity and individual pointer readability. Last but not least, it might be tempting to go for the best of both worlds and write account for the single object and accountCollection for the list.

I usually Runaway from that last one because it breaks syntactic parallelism and might give the reader the impression that there’s more difference to what they do semantically than a singular/plural thing. And after a while thinking about this, I’d say it’s a tight fight between forms 1 and 2: on the one hand, I’ve had several minor productivity setbacks overlooking the trailing s over the years and, as such, tend to prefer the latter. But on the other hand, I can certainly see that if a team builds a strong and horizontal culture that singular and plural are the way to go, double-checking that kind of stuff could become second nature to everyone and tip the scales towards the first option.

Iterators

Walking through a collection of items and doing something with them is one of the bread-and-butters of programming life. Regardless of what you're writing, there are going to be iterators all over your code. And even though the more high level programming languages may abstract that for you, there are still a few that don't, and for them there's a very simple naming trick: instead of writing i , j , k and the like for iterator variables, try using ii , jj , kk and so forth. This one effortless change improves searchability** tenfold while maintaining the standard expectation on these variable names.

**I know that this is arguable and that there are a lot of code editors out there with advanced search features that could help with this without using the trick, but its so effortless, portable and editor-agnostic that I still think its a decent idea.

Service Objects

Service Objects (SOs) are a great concept and have a lot of space in today’s web apps, but usually bring up a few naming mishaps. Look at this service object folder, for example:

This is a pretty good (and real-life) illustration of the controversy surrounding service object naming. First, note that even though some people tend to call these classes SOs, the SOs themselves are actually the instances of SO-describing classes. Then remember that, for the classes, the natural way is to name them after nouns, and therein lies the issue. We see paginator , deal_notifier and a few ending in metric , cool. But we also see clone_investment , upsert_investment and cancel_<something_complicated> (God Bless This Mess).

Wait, verbs ??? 😱😱😱

So, yeah. What happens is that SOs as a design pattern have the purpose of implementing a single operation that makes sense in your business logic, the actual service they're providing you with, their very raison d'être. Their public interface is usually made up of a sole method, possibly static, and usually named call . And since they can't do anything else, developers started thinking it'd be reasonable to name them after the action they will perform once call -ed, thus releasing themselves from the clutches of one of academic OO's most iconic naming standards.

I resisted that myself for a while, thinking it could be Bad Medicine. "Why can't we just name them with nouns and use them the exact same way? InvestmentCloner.call() doesn't look so bad". The thing is their instances differ from most because they have a very well-defined lifecycle: they'll be created, called upon to do their thing and (hopefully) die gracefully*. So developers (especially the ruby community, who are known for favoring readability) started thinking that naming them after the actions they perform, such as NotifyCustomer or AbortMission , could make for quicker code apprehension without any semantic loss.

*Using singletons to implement service objects is kind of an anti-pattern. The global visibility, long life and likely statefulness of a singleton is too hard to test and too side effect-prone. More in-depth discussion on this theme can be found here and in the linked questions.

Minimizing abstraction leaks

The awesome and timeless 2002 Joel Spolsky article ‘The Law of Leaky Abstractions’ brings to light an essential flaw in programming understood as the craft of implementing incremental, layered abstractions. In a nutshell, he theorizes that “all non-trivial abstractions, to some degree, are leaky”, in which they fail to do what they’re supposed to while completely shielding the user from their inner workings. This is particularly important for us because bad naming is a huge source of abstraction leaks, which in turn means we can minimize or even completely avoid them by taking proper care with what we’re saying they do.

So, we're looking for names that on the one hand empower the entity, implying their general "area of expertise", but that on the other hand are careful enough to restrict these expectations as to avoid suggesting too much power. It comes as no surprise that the overall architecture usually profits from this, since the developer is obligated to pay closer attention to the relationship between entities and the bounds of their roles.

Ok, cool, but let's see some code

So, let's move away from bullet point-guidelines for a bit and build something up step by step while trying to avoid other aspects of poor naming.

Say we want to write a service to connect to Instagram and do instagrammy stuff like fetch somebody's posts, crawl comments to a certain post, get likes to said comments and the sort. We could start off thinking of a name for it:

This doesn't say much about the class, except that it has something to do with Instagram, duh. As far as we know, it could as well have methods to remotely implode the Instagram HQ. Let's try something clearer:

Ok, this isn't perfect but says a lot more about the stuff I want to represent. I already expect a class whose objects will crawl Instagram for stuff. Still, it strikes me as too powerful and monolithic an abstraction, which can have too many lines of code, be more confusing than it needs to be, require too much studying to figure out, easily cause abstraction leaks or all of the above. Maybe we could break it down a bit:

Alright! Now we can further restrict our expectations of the crawler abstraction and believe it won't care about talking to the instagram API itself, relaying this stuff to InstagramClient *. At the same time, we created a perfectly reasonable character for abstracting the service that worries about interfacing with the Instagram API, with the added benefit that InstagramCrawler doesn't even know or care if this communication is gonna be via REST, GraphQL or some other weird protocol.

We're gonna stop here for the sake of this example, but if you feel your 'crawler' does far too much stuff to be in a single class or that your 'client' could also be further broken down, this isn't necessarily the right point to stop refining the abstractions.

*Real-world applications probably would allow for injecting the client for testing and decoupling purposes.

Now let's get One Step Closer and think a little bit about error treatment, and begin by creating a custom InstagramError that extends Ruby's StandardError :

So, while this could potentially represent every error our crawler could spit out and quickly solve our problem, it's missing out on a perfectly good opportunity to make the developers' life far easier. By putting in a little more effort at this point and restricting exception abstractions a bit more, we could save hours of slow debugging time by better describing what kind of errors took place:

(Of course, in order to raise these errors correctly we'd need some additional error treatment code im deliberately skipping for the purposes of this analysis.)

What About Now? This already looks like a giant timesaver during debugging time in which the devs will much more quickly be able to discern what problem took place without having to go through logs or huge response message outputs.

However, it exposes a gaping abstraction leak by having the Crawler know about and have to deal with communication and protocol issues such as MalformedRequestError and InvalidAccessTokenError . But we have just the place to fit these in, don't we?

This is the final form of our little example case study, which is an adapted subset of real-life code which has been in production for several years. Proper care with naming aided our team in avoiding abstraction leaks, semantically dividing responsibilities among entities, simplifying the debugging process and made us write overall clearer, more self-explaining, understandable code.

The meaningless abstraction

Before we wrap up, I’d like to show an unstructured example of something that not rarely pops up in code reviews, making me feel Shot Through The Heart:

This is an extremely simple React component that doesn't do much except for wrapping its children elements in a div tag. And in spite of its simplicity, at first I had no idea why someone thought it would be a good idea to name it Auth . "Maybe it was a bad name for an authentication component 🤔". Just it isn't, since it doesn't implement any authentication behavior or appearance. It's also not some weird standard React boilerplate, so we're left with a meaningless/misleading abstraction, a pair of name and entity that doesn't help us at all to discern or put boundaries to the latter. If we go deep enough down the rabbit hole, we may even find it to serve some twisted purpose (a master component to group up authentication sub-components? a testing selector?), but the name doesn't point us towards its architectural relevance and the implementation raises a yellow flag right off the bat.

Closing words

Two main things motivated me to write this blog post. Firstly, It’s My Life: whenever I'm assigned to a project that is already underway, I see that my biggest onboarding roadblocks hinge on unclear project architecture/folder structure and bad naming. It usually feels like trying to internalize a rational, working model of an Escher drawing: even though it somehow works, it makes little sense and seems impossible to tie all ends without creating new loose ones. Secondly, there seems to be a noticeable lack of reading material discussing the subject outside the context of specific languages or particular/recurring naming conundrums.

So, all in all, These Days seemed like a good moment to give others Something For The Pain and write down a few ideas along with established practices. Hopefully some new devs will pop in here and come out knowing that good, proper naming isn't one of those things you learn and then forget as soon as you finish school. Plus, I fully expect these ideas to foster discussion and spark up at least some controversy among the more experienced, so readers are more than welcome to bring old and new thoughts to the table.

Now let's put on some loud Bon Jovi and go back to coding. Have a Nice Day!🤘🤘🤘

P.S. Just so I'm not Misunderstood, let me give y'all Something To Believe In: the random capitalized words throughout the text are not random at all. Raise Your Hands in the comments or clap if you found them all! ;)