Can You Explain Your Code?

By: Amy M Haddad

Programmers often mistake a working program for an effective one. Their code could be a nightmare to read and debug. It could take forever to run. It could be filled with poorly named variables. No matter. As long as their code works—that is, it yields the correct result—then they’re happy and move on.

This is the wrong attitude to have.

Getting the program to work is only one part of writing an effective solution. Other factors include: clarity, meaning, and performance. So instead of focusing exclusively on correctness, we need to also focus on effectiveness.

A step towards writing effective solutions is to explain your code line by line and read it out loud. This is a great way to gauge the quality of your code and your knowledge of it, as well as find ways to make it better.

The better you know your own code, the more effective solutions you can write. If you know what each line of code does and why, then you can see alternatives and make tradeoffs, which ultimately leads to writing effective solutions. And that’s our aim as programmers: to write an effective solution, not merely one that works.

Aim to Explain

It seems so easy. “Of course I can explain my code,” you may be thinking.

I encourage you to give it a try: start at the top of your program and explain each line of code out loud to yourself.

The task is often harder than it seems.

That’s because there’s a difference between explaining and describing. When you explain something, you move beyond surface level to unearth what’s happening and why.

Take this line of code as an example:

sentence_letters = set()

To explain this line of code, I’d say: “sentence_letters keeps track of the unique letters from the provided sentence, since the sentence may have multiples of the same letter.” Given the context of the problem, that’s exactly what sentence_letters does (keeps track of unique letters) and why it does this (the sentence may contain duplicate letters).

Explaining is different than describing. To describe this line of code, I’d say: “create an empty set.” But that doesn’t tell me a whole lot. What’s the set doing and why does it matter?

This is a simple example to drive home a point: aim to explain. There are reasons why.

Pass the Knowledge Test

First, explaining your code is a knowledge test. If you have trouble putting words around a line of code, then you may need to revisit a concept.

You’ll see the same concepts, approaches, and data structures in future problems. So it’s better to be aware of your knowledge gaps and do something about them, than to let them fester over time.

Besides, doing a bit of research on trouble areas may help you to improve your current solution. You may find a better way to use the data structure or approach. Or you may come across something new that’ll greatly improve your solution.

And that brings us to the next benefit: explain your code to improve it.

Make It Better

Verbalizing your code is a great way to catch errors and spot opportunities to make your code better.

That’s because when you read your code out loud you engage another sense: your hearing. And that’s a good thing: what you catch with your eyes can be very different from what you catch with your ears.

If you read your code and it sounds awkward or cumbersome, then it probably is and should be updated.

At the same time, working and re-working your code will cause you to catch things you overlooked, like poorly named variables.

A Critical Skill to Build

Identifying your mistakes and areas of improvement and doing something about them are a part of a critical skill: self-assessment. This is reason enough to explain your code.

It’s one thing for someone else to point out your mistakes. But it’s something else entirely to train your mind and eye to spot them yourself, and to fix them.

At the same time, it’s also worth noting successes. Find something you did well—and understand why—so that you’ll do it again.

After you explain your code, make flashcards to really nail the concepts. I use Anki: a free and open-source flashcard program that uses spaced-repetition. I make flashcards to remind me of things I did well (so I do them again), as well as concepts that I need to work on. The idea is to regularly revisit the core ideas that I learned about or used while explaining my code.

Make It Happen

The easiest way to build a habit is to tie the new thing you want to do (ie, explain your code) to something you already do. Say the last thing you do before you call a program complete is to run all of the tests one final time. So run the tests, then explain your code.

I use a problem-solving checklist. It contains small, but important tasks to do before I call a problem complete. The last item on my list is to “explain code.” Using a checklist is an easy way to ensure your solutions are accurate and complete before you call a problem “done.” Plus, it makes it easy to incorporate a new habit, like verbalizing your code.

It’s common to hear about people gripe about the quality of code these days. Explaining your code is a small time investment that can yield better, higher-quality code. It's low-hanging fruit that you ought to take advantage of.