Why You Should Write Clear, Meaningful Code (and How to Do It)

By: Amy M Haddad

It's sometimes thought that short, "clever" code is the aim when writing programs. However, shorter isn’t necessarily better. Neither is “clever” code. You know, code that reads like a cryptic puzzle, which causes you to spend an unnecessary amount of time trying to figure out.

We shouldn't aim for short, terse code. We shouldn’t intentionally make code complex or confusing. Instead, the best type of writing, be it prose or code, is clear and meaningful. This should be our aim.

That’s because it’s the easiest for the reader to understand. “Clarity is not the same as brevity,” writes Brian Kernighan in the book, The Practice of Programming. "Often the cleaner code will be shorter . . . but it can also be longer . . . the proper criterion is ease of understanding.”

Clear writing is also indicative of our thinking. Writer William Zinsser puts it best: “clear thinking becomes clear writing; one can't exist without the other.”

So if your writing (be it prose or code) is complex and confusing, then there’s still work to do. As you refine your writing, you’ll refine your thinking. You’ll figure out what you’re really trying to convey in the process.

Clear and meaningful writing offers a wonderful reward: effortless reading. Variables are well-named. Functions have a specific purpose. The program is well-designed. In fact, the code reads like a book.

Effortless reading comes at a cost: it’s hard work. As any good writer of prose or code can attest to the truism: “easy reading is hard writing.” But it’s something we ought to aim for.

Anyone can make something complex. It’s so much harder to take something that’s complex and make it clear and meaningful. Here are six ways to do it:

1. Write meaningful class, function, and variable names.

The names we choose in the code we write have such an impact on readability and meaning.

One letter variable names, for example, can be confusing or misleading. The reader may not realize what the lone variable t represents, so they have to assume based on the context. Such assumptions can be a recipe for disaster. It’s equally confusing when a variable name is plural when it should be singular (or vice versa). Does the variable represent many items or one item?

Writing meaningful names is hard to do. Steve McConnell’s book, Code Complete, offers excellent naming advice:

“State in words what the variable represents. Often that statement itself is the best variable name.”

So ask yourself: “What does this variable represent?” In my experience, and to McConnell’s credit, the answer to this question is often the best variable name.

2. Refactor.

Many writers spend much of their time editing. It’s one thing to get words on paper. It’s quite another to have them make sense.

The same ought to be true with code we write: we should spend more time “editing” (or refactoring, for our purposes).

Let’s be honest, our first attempt at a problem is usually not the best—even if the solution is correct. There’s always room for improvement, whether it’s a better algorithm, data structure, or variable name.

3. Read your code out loud.

After I write an article (including this one), I read it out loud. If a sentence sounds awkward or confusing, it probably is and should be changed.

This is a great practice to do with the code that you write for the same reason. It’s also a great way to spot errors that may have been overlooked.

4. Create a programming checklist.

Use a checklist to outline the important steps involved in writing a program or solving a problem.

A checklist gives you peace of mind that your work is accurate and complete. It also reminds you of important tasks that may slip your mind, such as meaningful variable names, while in the midst of coding.

5. After you solve a problem, study the code of others who’ve solved the same problem.

We shouldn’t just be writers of code. We should also be vast readers of it.

By reading code regularly, you’ll pick up ideas on design; learn about problem-solving strategies; and find out new things about a language. As you add more tools to your programming toolbox, you’ll also expose yourself to different code-writing styles.

Awareness can be a great teacher: simply being aware of good and poor code can help us become better writers of it.

LeetCode and Exercism are great problem-solving resources because both offer community solutions to learn from.

6. Read William Zinsser’s book, On Writing Well.

Zinsser’s book is for writers of prose, but many of his principles are applicable to our work as writers of code. After all, writers of prose and code are in the same business: communicating clearly.