The Eight Buffalo Rule: How to stop writing unreadable code
Tags: beginners, tutorial, codenewbie, learning
Published: 2020-07-05 13:49:21

# Eight Buffalo

> Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

The eight-buffalo sentence above is commonly cited as the longest grammatically correct sentence you can write with a single word.

On the surface, it looks like nonsense. None of the words communicate any intent. You can't pick out which are the nouns, the verbs, or the adjectives. There appears to be no structure, just a string of Buffalo with an occasional capital letter.

But the sentence is not nonsense, because you've been told it's not nonsense. There is *something* at the heart of these words that you must decipher.

# Communicating Intent

This might be how you feel when you look at 'unreadable' code. You know that the code does something, because the computer understands it. Like the eight Buffalo, it's grammatically correct.

But the code is not communicating its intent to you. No clear mental pictures spring to mind. You have to pick through, word by word, to extract the meaning.

Let's break down the buffalo, and see what they can teach us about writing readable code.

# The buffalo are from New York

Buffalo is a place - the city of Buffalo, in New York. Whenever a capital letter is used in the sentence, it's referring to the city.

> **Buffalo** buffalo **Buffalo** buffalo buffalo buffalo **Buffalo** buffalo.

From that, we can deduce that when 'Buffalo buffalo' are mentioned, it's talking about buffalo from the city in New York.

Let's help ourselves out by exchanging 'Buffalo' for 'New York'.

> New York buffalo New York buffalo buffalo buffalo New York buffalo.

Alright, we're getting somewhere. The sentence is not completely decoded, but now we have a mental picture of a buffalo from New York, perhaps wearing a New York Nicks cap and eating a hot dog.

In coding terms, we renamed a variable. We took 'Buffalo' and renamed it 'New York'. With that small change, we now have a mental model that we can use to help decode the rest of the sentence.

# 'buffalo' means 'to bully'

To buffalo someone means to bully them. TIL. Let's apply what we learned before and rename another variable. But which do we rename?

> New York buffalo New York buffalo buffalo buffalo New York buffalo.

Because of our mental model, we know that 'New York buffalo' makes grammatical sense on its own. So let's rename every 'buffalo' to 'bully' that isn't a part of the 'New York buffalo' pairing.

> New York buffalo New York buffalo bully bully New York buffalo.

Another mental model comes to mind: buffalo from New York bullying other New York buffalo. We've learned two things - what the New York buffalo are doing, and who they're doing it to.

This time, we've renamed a function. A well-named function can not only clarify _what_ is being done, but also _why_ it's being done and _who_ it's being done to. Functions are the verbs of development, and thus are the most important to name correctly.

# Adding separations

But we're still not at full clarity. The sentence still feels mashed up - too many words and not enough punctuation. Let's add some joining words.

> Buffalo from New York, whom other New York buffalo bully, bully other buffalo from New York.

Suddenly, clarity. The separating words and punctuation help give a rhythm to the sentence. The relationships between the words are clearly explained, and each clause of the sentence has enough room to breathe.

Here, we've modularised our sentence. The parts that relate to each other are grouped together. The individual parts are spaced out into separate sections, so you can focus on one piece at a time.

# It's all buffalo to me

The most interesting part of this exercise is that, once it's explained, this sentence becomes clearer:

> Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

Imagine you did the coding equivalent of writing this sentence. To you, it might seem perfectly clear. You don't need the renamed variables, renamed functions, and modularisation to understand your code's intent. After all, the code's intent _is_ your intent.

Once in a while, take a moment and step back. Consider whether you're writing buffalo. The moment you notice it, your code will improve.