Don’t Just Write Code, Read It Too!

"Code is read more often than it is written."

It's a famous aphorism among coders and one that, I think, is generally accepted. The quote is sometimes attributed to Robert Martin, although the direct quote from his book Clean Code is more specific: "Indeed, the ratio of time spent reading versus writing is well over 10 to 1."

Ten to one! And in my experience, that estimate is conservative.

So here's a question for you: Do you spend an order of magnitude more time practicing reading code than writing it?

The Skill No One Talks About

I see it everywhere: "Code should be readable, so focus on writing readable code!"

It sounds like great advice, but it misses the mark. The focus is on the wrong part of the communication cycle. If you want to learn how to write readable code, you better spend a lot of time being a reader and paying attention to your needs.

One of the great truths I've learned about "readable" code is: You don't have to cater to the lowest common denominator. The goal of readable code isn't to be read easily by anyone. Instead, the goal is to be understood by a target audience. Or, in this case, all three of them:

1. The compiler.
2. The author.
3. Future maintainers.

Appeasing all three is challenging, and I don't hear anyone discussing the secret.

Read Well To Write Well

There's an interesting parallel between writers and coders. The best writers I know are avid readers. The best coders I know spend lots of time reading code, too.

It's not all that surprising, though, since programmers are technical writers in a very real sense: they communicate technical ideas through writing to a technical audience. Instead of prose, they write computer code.

Reading code helps you:

1. Shift your perspective: You'll notice things you'd miss while writing.
2. Understand obstacles facing readers: As a writer, addressing your audience's problems is essential.
3. Grasp the big picture: It can be easy to get "writer's blinders." As a reader, you're forced to juggle a lot more context.

As with any technical writing, communicating technical ideas through code requires a thoughtful and strategic approach. That's something that you can only improve by honing your skills for both writing and reading code.

Putting It Into Practice

Here are three short exercises you can use to practice reading code. They each take ten minutes or less.

#1 - Identify Intrinsic and Extraneous Load

I learned about this exercise from Felienne Hermans' excellent book The Programmer's Brain. It's been a real eye-opener.

Your brain experiences two kinds of cognitive load when solving a problem:

1. Intrinsic load, born from the complexities of the problem itself, and
2. Extraneous load, caused by external factors, such as implementation details.

To illustrate the difference, and to borrow Herman's example, consider the following Python functions:

def function1(items):
    return [n for n in items if n > 10]
    
def function2(items):
    above_ten = []
    for n in items:
        if n > 10:
            above_ten.append(n)

Both functions solve the same problem: they filter a list of items to include only those greater than 10. The intrinsic load is the same.

The extraneous load depends on your experience, though. For a Python coder who is unfamiliar with list comprehensions, function1 might be difficult to grasp even if they can produce function2 without difficulty.

You can make a table to identify the intrinsic and extraneous load on each line of code in a function. For example, here's a table filled out for function2 in the preceding example:

I've used a template provided by Hermans in her book, but you can just as easily make your table with pen and paper or the notetaking app of your choice.

#2 - Draw a Dependency Graph

Pick a function from a codebase you are unfamiliar with and print it out (or save the code as a PDF or another digital format that can be annotated). Then circle all of the variables.

This exercise also comes from The Programmer's Brain, but I've been doing it since my first coding class in college.

For example, here's function2 from Exercise 1 with all of the variables circled:

Next, draw arrows connecting earlier instances of a variable to the ones below or to the right:

This visualizes how data flows through a function or other code, highlighting how each line depends on previous ones.

#3 - Make a Call Tree

Pick a function from a codebase you are unfamiliar with and draw a hierarchy of function calls made by the caller and each of its callees. Then drill down into those functions and do the same.

For example, here's a call tree for a Python program that analyses users' typing speed and accuracy:

The call tree serves several purposes. It shows you all of the functions used in the code so you can quickly identify any gaps in knowledge. The tree also exposes the logical hierarchy of the code. You can see the layers of abstraction, or lack thereof, and understand how they interact.

Read Next

Learn how the science of cognition helps explain what makes code confusing and how a simple rule can help you transform confusing code into clean code that is easy to read and understand:

Want Cleaner Code? Use the Rule of Six

A simple and powerful framework for ironing out confusing code.

Curious About CodeDavid Amos

Dig Deeper

Each of the three exercises in this issue can be done in a few minutes. Spend 10 or 20 minutes daily practicing the exercises for the next two weeks. Find some code on GitHub or use a codebase from your job. Just make sure it's code you haven't read before!