3 Things Coding And Prose Writing Have In Common According To Cory House

Something interesting caught my attention in Cory House’s Pluralsight course, Clean Coding Principles in C#.

House makes a strong case between writing code and writing prose. As a writer myself, I’ve long seen the parallels between writing and coding. However, House takes the analogy further, and draws many parallels between writing clean code and the writing you’d find in a book or article.

The analogy is a good one because it’s concrete and relatable: all of us read books and all of us write code.

We know a book is well written when reading it is easy. That’s because:

• Chapters are organized.
• Headers give us specific information about the paragraphs that follow.
• Each paragraph contains one idea.Each character is developed.

We can apply the same principles found in writing prose as in writing code. House shows us how.

1. Write variable names that clearly convey your intent, like names in a book.

“Imagine reading a book with random, one-letter abbreviations throughout,” House suggests. Here’s an example: “P was very angry with G for insulting her M...He slept on the C.”

Despite the bad names, House acknowledges, you can probably get the main idea of what’s going on. But you have to work at it.

That’s an important point: the reader shouldn’t have to work at it. It’d be much clearer and easier to read something like this: “Pam was very angry with George for insulting her mom...He slept on the couch.” The abbreviations have been replaced with clear, meaningful names.

The same principle is true when writing code. It’s clearer and easier to read a variable like employee_total instead of seeing a seemingly random letter, e. “Understanding the programmer’s intent is the biggest problem,” House says. “So we must strive to be crystal clear about what we meant to do.”

Key point: Be intentional with your names.

2. “Functions are like paragraphs, for code.”

In school, most of us learned the golden rule for writing paragraphs: one idea per paragraph. A similar rule applies when writing functions: each function has a single purpose.

Key point: It’s easier to read and understand—both paragraphs and functions—that are clear, focused, and don’t do too much.

3. “Initialize variables just in time,” like characters in a book.

You don’t get a list of characters up front when reading a book, House points out. Instead, you’re introduced to a new character “just in time.”

For example, we get introduced to Bob when he enters the story. Otherwise we have to keep track of Bob, Alice, and a slew of other characters unnecessarily. As a reader, that’s burdensome. It makes reading confusing. It’s why authors don’t do this.

The same is true when coding.

If you initialize all of your variables at the top of your file, then the reader has a bunch of things to remember. That’s burdensome. It makes reading confusing. Don’t do this.

“Instead, well-structured functions should....initialize variables just in time,” House says. “When the variable is needed, bring it to life.” Then, get the variable “out of scope.” That way, the reader no longer has to think about it.

Key point: Give your readers what they need—when they need it.

It’s been said that easy reading is hard writing. That’s true for writing both prose and code. Make it easy for your readers: write clear, meaningful code.

Programmer and writer: amymhaddad.com | programmerspyramid.com | I tweet about programming, learning, and productivity @amymhaddad

Originally published on amymhaddad.com.