Telling a Story with Your Code

Latisha McNeel, Full Stack Developer at G2i

This article first appeared in G2i.

Programming is part art and part science. How does story telling with your code fit into this dichotomy?

A story is an accounting of a set of events or people, real or imaginary. Code is either a system of words, letters or figures substituted for other words, letters or figures, especially for the purposes of secrecy or programming instructions. Sometimes, while reading code (computer science), both definitions apply. In the talk about inclusivity, everyone, all humans, should be able to use the applications or products we build. If we are building for everyone, why then are we writing code like we only want those with our decoder ring to be collaborators? Or we only want the computer to be able to decode what we wrote?

Whether we are writing a novel, a short story, an article or code, our audience is always our fellow humans. The computer can interpret the statements whether we use the most concise way of writing an algorithm or whether we use the most readable way. Sometimes we will care about the optimization of a line. We will need the line to be faster. What we always care about is whether or not we can understand what the line is doing when we read it. Having to guess about what a line of code is doing fuels the imposter syndrome that so many of us fight with.

For the most part, we build our applications with high-level programming languages. Programming languages that are meant for humans to be able to understand and must be compiled or interpreted for computers to understand. If we are writing in a language that will be translated for the computer, why are we still writing code that requires so much translation for humans as well? ‍

What is telling a story with your code?

Some people think programming is science and math with rules and formulas. Others think programming is an art. The computer will see code in black and white, right or wrong, on or off — two choices. Humans will read code and will read it subjectively, the same way they read a news article or Shakespeare. Art is subjective, and because we are critics, we tend to stereotype art as without rules whereas, with science, we want to be methodical, follow a formula, prove something “right.” Even then, science and art are not all that far apart. Architecture both uses math and science, and yet, we call buildings beautiful. We try to find new ways to combine the rules into more beautiful structures. Art uses science when combining two colors to make a new color and has rules for composition. Programming is also both science and art, and writing code is still a form of writing. ‍

Where do I start telling the story?

The story starts with the architecture and the folder structure. Uncle Bob says that “good architectures scream their intended usage.” A portion of the architecture is the folder structure and naming the folder structure. On naming things, Uncle Bob states that “choosing names in programming is as important as naming your children.”

On that, a programmer needs to know the business and have good communication with the stakeholders. The group needs to decide on a taxonomy. If the naming of things is based on the terminology in the business, then the programmer can talk to the stakeholders and discuss the code with more clarity. Remember, changing the names of things in code is usually a cheap operation. A good coding editor does most of the work for you. Knowing everything about the business on day one is not necessary.

In naming the nouns and verbs of programming, we start with the taxonomy of the domain or business. We may use a thesaurus to find a better word for a word that doesn’t seem specific enough. We may question the same word being used in different ways. This leads to a comparison of DRY principles in writing a novel and in writing code.

In writing a novel, I use a thesaurus to vary my word choice and see if I can find a more descriptive word when I realize I used the word “walking” 20 times and maybe “strolling,” or “running” was a better choice. In programming, DRY means I don’t want to write the same block of code multiple times — I don’t want to have to maintain code that does the same thing more than once. In programming, I absolutely want to use the same word to describe the same thing every single time. I want consistency with word choice. ‍

What is an example of telling a story with code?

Look at the following two code samples:

It is only a couple of object declarations — a character, in a game, in a story — we don’t know. But there are some differences. Is the general character better than myCharacter? I think so. Ultimately, this may not be my character — it might just be a character in a game I build with other developers. The prefix my is extra — Grammarly tells me I use extra words when writing all the time.

The other difference is a property declaration — one isMoving and the other is just move. Does the extra word make a difference in the readability, in the story here? The first one tells me that the character named Latisha is moving. We don’t know much else, but we know that Latisha is moving. The second one just says move:true. That leads to more questions. Is Latisha moving, does she have the ability to move? Is move a verb or a noun in the property? We don’t know — we can make assumptions, but the line is open to interpretation.

We don’t know if the character has the ability to move — as in walk, fly or run OR if the character, should actually be a user, and is moving houses or apartments. How many stories can be invented with just the above samples? How could we change the details to allow the next developer or reader more context in the story we are telling?

One more code sample — references the objects above:

How do the above statements read?

One asks clearly if the character is moving. We still don’t know if the character is walking or if the character is moving houses.

The other one, asks if my character moves? It’s a way more ambiguous question. ‍

How do I improve my ability to tell a story?

One important trait: caring.

You need to care about your code and you need to care about the audience who will read your code.

Three items for gaining experience:

Reading
Writing
Reviewing/Refactoring

Uncle Bob states the ratio of reading code to writing code is 10:1. Stephen King states that “the more you read, the less apt you are to make a fool of yourself with your pen or word processor.” When you read code, be critical. Notice the good and the bad. Notice your first reaction to what you are reading. Pay attention to the story you are building in your head as you read the code.

You can read code all day, every day. If you never start writing any and debating on the word choice, you won’t ever get experience actually writing code. It doesn’t matter where you start and it doesn’t need to be perfect the first time. Start with what you know. Kent Beck says, “Make it work; then make it right; then make it fast.” In that, focus on readability and the clarity of the story you are building.

Reviewing and Refactoring. You need to review your own code, you need to refactor your own code, and you need to have other people review and refactor your code. If you were writing a paper for a class or an article or a novel, someone would review it, or edit it. You may leave it for a while, for a month, for 3 months. The more time that passes, the less bias you will have when you reread it. It will seem like a new story, and you will have more experience coding. ‍