Narrative Code


In starting this series, I was confronted with the dilemma of which area of programming should I start with? Testing? Data Modeling? Language Types? All of which are very important topics and areas that any good developer should know. However, I felt strongly that the best area to start was not with code at all but writing.

As a developer we tend to write our code for one person, ourselves. Yet most of the time our code can live longer than the tenure at a job. Or even worse, you are forced to revisit code you wrote years ago and have no clue what it does.

Hard to read code is frustrating for anyone and everyone who has had the displeasure to support it and yet most developers don’t practice good writing in their code. Often the excuse can be that they are under pressure to deliver or the code is self-explanatory. But in most cases, it doesn’t make sense to others or it the context of the function is no there.

So how do we become good programmers? By becoming good writers.

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

Martin Fowler

An Outline

Most developers will tell you how well Test-Driven Development (TDD) helps aid in code development. It does so by creating a template for how your code is supposed to work by how it will be tested. In a similar way I would advocate for NDD (narrative driven development) by first outlining what work you will be doing.

If you are starting a new project, write the README of what the application or library will do. This gives a broad overview and allows you to establish a focus for the project from the start.

If you are writing a new feature or bugfix, write up the pull request or commit comment before your start. It may not have all of the details but again established a context for the future reader.

Or if you are writing a function or method or a new object put comments at the top and throughout to establish a focus for what the work will ultimately do.

Then go back and write you tests before you write your code :)

What’s in a name?

“Because it is my name! Because I cannot have another in my life!”

The Crucible, Arthur Miller

Names of things are important. And sometimes it can be really hard to name something in your code. But these names are supposed to convey an important meaning to both the developer and to the future developer. Often, we’ll get caught up with the names of objects or API endpoints but will be careless with the names we give our methods and variables. This is a huge mistake because often this variable or method may only be used one or two times but in the lifespan of the code may be read hundreds, so it better be clear.

The names of variables and functions should help deliver clarity and purpose to the code. I cringe every time I see String a or even worse String a1 as variable names when they should really be named domainPortionOfGivenEmailAddress. Sure, it’s lengthy but when used it will make sense. In fact, some frameworks like Spring encourage the use of lengthy method names to convey the purpose of the method. An example of this is Spring Data’s Repository methods which allow you to write methods like List<Stores> findAllByCityAndState and will generate the query call for you based on the name.

In the end the name is an important step towards readable code and is really one of the simplist changes you can make as a developer.

Don’t keep your comments to yourself

Ever come across a loop and wonder what the heck it was doing? Or a function that you aren’t quite sure what it does? Or just really don’t want to have to think about any of this stuff while doing a ten file code review?

I have a few comments on this.

We should be writing more comments in our code because it helps control the flow of the way we read the code. Again, the context is key to anyone entering in to support the code and defining comments before you even write a single line can help determine its structure and establish its purpose.

Java in fact encourages the use of comments around objects and methods through Javadoc which helps the developer establish the purpose and allow consumers to easily use the functions that are written. Taking the time to write out this information will pay dividends in time spent by yourself and others in the future because they won’t have to ask you, “what does this do again?” and prevents possible repeated code.


As stated in the introduction a README file can help establish a goal or purpose to any project, yet it is often the last thing written. It makes sense to fill in technical bits of the README as you go but an Overview and Purpose statement could easily be written at the beginning. This is to underline the motivation and reason for doing this project and will help you know if you are straying from its purpose.

While writing the code you will run into configuration that will be needed or limitations of your product. PUT THEM IN YOUR README! Doing this sooner rather than later helps prevent it from becoming Tribal Knowledge and helps you iterate over the process. Plus, it will help you give some visual cues to possible issues. “Wow it takes twenty steps to set this up, maybe I should rethink this or at least include a script.”

Tools like Github encourage you to include README files on your projects and you should take advantage of them. In my experience the README should be the pulse of your project. Put in setup instructions, versioning information, code coverage, reviews, anything really because it becomes the most useful piece of information available to those who want to use it.


In the end this is all about making your life and the lives of your coworkers easier. Writing should be as natural as speaking and by writing code like you would a story helps you, the writer, establish the flow of your application. Through proper writing you will establish context, perspective, and purpose for the reader who is either reviewing your code or fixing a bug. In the end code is read more than it is written and so we should make sure it’s pleasurable for those who read it.

Joel Holmes
Software Developer