Cognitive load and the importance of naming

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

What is cognitive load?

When I had Human-Computer Interaction classes in college, I got acquainted with the concepts of Cognition and Cognitive Load. My teacher showed us a very simple example to explain what are those concepts, compare the following examples:

  1. 551153219421
  2. 55 11 5321 9421

The second example is obviously more simpler to comprehend and also may lead us to think that they are maybe telephone numbers. That means the second example has much less cognitive load, i.e., you need less mental work to give those numbers context and meaning.

What does it mean in code writing?

That also applies to naming things in our projects, and heavily. Imagine a new co-worker in your project having to learn all the names and concepts. If you can ease the burden by naming things well, your fellow colleague will be a lot more productive.

I’ve been working on my Outpost gem and there’s a part on it that verifies your system’s output in order to tell whether the system is failing or not. I called it “hooks”. This is a nice example on how bad naming can affect comprehension of a project.

Let’s give it a little bit of thought. What does “hooks” mean? It means, in computing, something that will be called back eventually. Ok, we got that part right. But what does it mean in Outpost? In order to fully understand the concepts, I have to:

  1. Understand the meaning of hooks in computing (not troublesome, since it is pre-acquired knowledge and it has a broad meaning)
  2. Understand what Outpost does
  3. Understand what a Scout does
  4. Apply the concept of hooks in the context of Outpost since the “hook” concept does not add much value to me
  5. Understand what hooks do in the context of Outpost.

Five “cognitive steps” in order to fully understand what the name “hook” mean in Outpost. But, after a while, during my work at Ruby Mendicant University, Gregory Brown suggested me to rename from “hook” to “expectation”. Expectation is also a common knowledge in computing, but even more, it has a very strong meaning for people used to TDD. So, now, to understand how “expectations” fit in Outpost, I have to:

  1. Understand the meaning of the word “expectation” in TDD
  2. Understand what Outpost does
  3. Understand what a Scout does
  4. Understand what an expectation do in the context of Outpost.

One less step. It is very hard to quantify how much did we gain in this simple name change, but we can feel there’s much less cognitive load involved. If you’re thinking the name you’ve chosen is good, try to think about the steps involved to understand the concept you’re trying to elucidate.

If you need more practical advices, Uncle Bob’s written a whole chapter about naming in his “Clean Code” book. In there lies a bunch of rules and tips on how to improve your naming by reducing the cognitive load involved in understanding code, getting closer to the path of having cleaner code.

Do you have this kind of philosophical thought about code as well? How do you make it practical and what are the improvements you’ve seen in your projects? Please share with us!

4 responses to “Cognitive load and the importance of naming”

  1. Another aspect of cognitive load is unnecessarily complex logic. A good example is double negatives which are sadly far too common – both in code and further afield.

  2. Nice post !
    s/comprehention/comprehension/ 😉

  3. Corrected. Thanks! 🙂

  4. Corrected. Thanks! 🙂