Posts de December, 2013

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

Phil Karlton

I was thinking about how important naming things is to me. Since the beginning of my undergraduate studies, I paid close attention to the names of every project I’ve done and every company or lab that I’ve worked at.

I’m also catching myself arguing about the name of things on my daily work and I was able to notice how bad I am at it. This post aims on forcing me to improve my naming things skill.

Regarding Project names

The last project we did at Globo.com had a good name. It’s called Sauron, and it’s main purpose is to collect and show server’s health, QoS/QoE analysis, handle video signals, network throughput, etc. It fits well as Sauron represents himself as an all seeing eye. It’s short, compact, nerdy, and I like it.

But we have a lot of bad names there: Streams-analyzer, EvoHandler and VMine are just some of then that are too vague or don’t really explain what they do (sorry coworkers, don’t take it personally).

My undergraduate project was called Marmota, an acronym for making arduino and mobile devices talk that forms the name of a funny animal in Brazilian Portuguese. I don’t know if anyone has looked at this fact, but I have no doubt that the name helped on its 15-minutes of fame [1][2][3][4][5].

Now I’m trying to engage myself on bem.tv, an attempt to scale live video streaming using P2P. Actually, bem.tv is another joke with a bird name and TV suffix, which refers to video broadcast. It’s small, simple and easy to say.

Yes, you must be thinking about the projects whose names make no sense but they’re much bigger and successfull than the ones that I listed. I’m not here judging the formula of success. I’m just concluding that short, solid names that make associations with cool stuff and the project purpose itself is a good formula. For me, a good logo as bower, gruntjs or yeoman also adds value to the project.

Regarding code

Naming classes, functions and modules are even more complicated. At our office we work with code that interacts with multimedia, and it’s common to deal with names that have more than one meaning. Stream, Signal, Media and Bitrate are constantly used in our codes, and those are a constant source of confusion.

For now we don’t have a solution for this, but docstrings on the code or a small meeting followed by a document describing the decisions and conventions should fix it. Since our projects are growing exponentially, perhaps it’s time to schedule this reunion.

Uncle Bob’sClean Code book have an entire chapter explaining names and how to use and improve it in your code. He defends that names must be pronounceable and searchable, and you as developer should avoid reader’s to mentally translate names (avoid mental mapping).

I agree that length isn’t directly related to self-explanation, and a good trick is look at your language syntactic sugars to improve the readability on the context at where your variable name or function is being used. I’m sure you’ll find something to enforce the name you chose.

Once in a while, ask people outside your team to review your code before pushing it to master. They will ask questions that were obvious to you and your teammates, but will alert where you are using bad names.

Outsiders have other context in mind, and their questions will probably improve your code design and names. It’s like visual design, information architecture. 4, 6 or 8 eyes is always better than 2.