Naming Things

A famous computer scientist at Netscape once said: “There are only three hard things in Computer Science: off-by-one errors, cache invalidation and Naming Things.

The first thing that God did when he created the universe is Naming Things (Genesis 1), and the first task He gave to Adam, again, was Naming Things (Genesis 2:19-20)

Naming Things is the foundation for successful communication. And communication is the foundation for successful understanding. Two people can only understand each other if they communicate in a common language.

Confusion is the absence of communication and understanding due to the absence of a common language. That is exactly what the word Babel means in the Hebrew Bible. And that is exactly what happened when God confused their common language. They did not understand each other anymore and thus their project failed.

“Now the whole world had one language and a common speech. As people moved eastward, they found a plain in Shinar and settled there. They said to each other, “Come, let’s make bricks and bake them thoroughly.” They used brick instead of stone, and tar for mortar. Then they said, “Come, let us build ourselves a city, with a tower that reaches to the heavens, so that we may make a name for ourselves; otherwise we will be scattered over the face of the whole earth.” But the Lord came down to see the city and the tower the people were building. The Lord said, “If as one people speaking the same language they have begun to do this, then nothing they plan to do will be impossible for them. Come, let us go down and confuse their language so they will not understand each other.” So the Lord scattered them from there over all the earth, and they stopped building the city. That is why it was called Babel — because there the Lord confused the language of the whole world.” (Genesis 11:1-9)

The purpose of Naming Things in software engineering is to establish a common meta-language in your source code that helps all developers in understanding the source code written by other developers. This meta-language establishes a common vocabulary, recognizable concepts, paradigms and structures, by implementing strong naming conventions, in order to let your source code self-document itself as much as possible, and in order to let your source code communicate itself as clearly as possible to all developers that read your code.

A Sinclair ZX81 programmer once said:

“Most of my work has been understanding how to change existing code. That involves reading it and working with it to understand how it fits together. Even when I write from scratch, two weeks in and I will be reading my own code back to myself to figure out what I did and why. The key point here is that no line of code exists in isolation. It’s not like you could ever type a line of code without understanding its impact on the whole system. That pretty much implies reading a lot of code.”

Another veteran developer says:

“With fixing a bug, I might spend hours combing through the code looking for the source of it, only to find that fixing it will require just a few keystrokes.”

In 2006 a study conducted at Microsoft with 157 developers found that roughly equal amounts of time is spent understanding code as other tasks such as designing, unit testing, and writing. In 2007, a survey of over 780 developers at Microsoft conducted by a team led by Cherubini found that 95% agreed that understanding existing code is a significant part of their job. Further, over 65% indicated spending time understanding existing code at least once a day (with over 25% indicating doing it multiple times a day).

Even Peter Hellam in his blog mentions that more than 70% of a developers time is spend understanding code as it is a preliminary requisite when testing code, modifying existing code or even writing new code.

One of the reasons Naming Things is one of the most important tasks in coding, is because that’s what you are reading, and even more important, that’s what you are communicating to your fellow developers. I personally always try to adhere to the following rules:

• Reuse common concepts. Stick to universal concepts in the industry. (reuse common concepts that are already established and well known to developers, for example concepts found in HTML, CSS, TCP/IP, SQL or common Operating Systems). Universal concepts from other fields can also be used, for example:

  • parent, child, sibling in hierarchical data structures

  • cell, row, column, tree in user interface layouts

  • atoms, molecules and organisms in atomic design

• One name for one concept. Try to always use one name for one concept. Do not reuse the same name for different concepts. This makes the code base more consistent and prevents confusion and reduces cognitive load.