You Are an Author

It’s true that you’re an author, but don’t be too alarmed. As a programmer you’re also an analyst, designer, coder, and tester. For now, let’s focus on being an author because it has a large impact on the quality of the code you write. There are two main writing styles for authors writing a book, and their followers are called plotters and pantsers.

Plotters create a detailed plan for the story. They know what will happen, who is involved, and how things turn out — all before writing any of the actual storyline. The term pantser comes from the phrase “flying by the seat of your pants”, which means doing something with little or no planning ahead. When pantsers get an idea, they start writing and figure things out as they go.

There’s a third writing style you might find useful. It’s a blend of planning and pantsing so its followers are sometimes called plantsers. They do just enough planning that they feel comfortable with the details, then start writing to see what happens — which sounds like an Agile approach to me.

As it turns out, programmers fall into similar camps. Some start reading the requirements for a program or feature and almost immediately begin writing code to implement a solution. They trust that, though it may take a while, eventually they’ll get it all working. Sometimes it works out, but non-trivial programs tend to be complicated and often the result isn’t pretty.

Other programmers read the requirement and start planning how to get it all done. Minimally, they’ll sketch out the structure of the program and what the APIs will look like before they start coding. They may even use an approach like Behavior-Driven Development or Test-Driven Development to ensure their code meets the user requirements. Programmers following this path tend to have fewer bugs and get their work into production sooner.

While the compiler doesn’t care about your writing style, the programmers who read your code will find it much easier to understand if you follow these three suggestions:

1. Use descriptive names in your code. Programmers expect names to have meaning: Good class, method, and variable names are critical to someone understanding your code. Use names that describe why a class exists, what a method does, and the meaning of the value stored in a variable.
2. Write several short methods that each do one thing instead of one long method that does several things. This makes it easier for your reader to understand what’s supposed to be happening so they can either verify that the code actually does what it should do, or modify it to do something different.
3. Use whitespace to identify related and unrelated things. Our brains expect related things will be near each other and unrelated things will be farther apart, so separating related lines of code within a method with one blank line, and separating methods with two blank lines, will help your readers see the relationships. It’s similar to the break between paragraphs in a chapter and the chapters in a book.

When you look at your code from an author’s viewpoint, I suspect you’ll find more ways to improve it. When you do, consider writing an article to share it with others. After all, you are an author.