Tech TLDR;

Writing Good Code is a lot Like Writing Prose

by

Table of Contents

Introduction

I love to write prose. I also love to write code.

Different people have different approaches to writing code. I had a co-worker whose criteria for writing good Software was to make sure that one block of code can be read without having to scroll.

My criteria for writing good code can be summarized with the following quote:

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

In other words, as Nicholas Zakas pointed out in his talk Maintainable JavaScript, if you open an editor and it’s blank – you are writing new code, if something is already there – you are maintaining code. We spend very little time writing new code and a lot of time maintaining existing code. For me, a good code is the code that I can understand without having to run a debugger.

I believe that there is a strong overlap between writing prose and writing code. For example, adding a small comment at the top of a module is a lot like adding an introductory paragraph at the top of a post.

Outline

I like to start writing my prose with an outline. It doesn’t have to be perfect, nor does it have to be final, but I find it to be a great tool for organizing my thoughts. Once an outline is in place, the rest of the writing becomes easy.

I believe that an “outline” is also a great tool for writing software. It is kind of like Test Driven Development (TDD), but without a big upfront investment. I like to take some time to investigate what functionality I am adding, what interface it might have, and what are some of the most probable use cases. Sometimes I can do it with an actual outline, sometimes I create a flow chart, and sometimes I just draw some thing by hand. The key is to take some time to think through what I am trying to build, before sitting down to build it.

Draft

After my outline is in place, I try to write everything I have to say to connect my bullet points. I am not worried about the quality just yet. I know that I will be able to proofread my writing at a later time.

I like to take the same approach with code. Once I have a general idea of what I am trying to build, I check out a new branch and just go for it. My biggest issue with TDD is that I find it too restrictive. Half of the time when I sit down to write something, I don’t know how things will end up working out. A different branch that I can easily throw away gives me the freedom to experiment.

Proofreading

After my draft is done, I like to go back and read my prose slowly out loud. I strive for my writing to roll of the tongue as if I am having a conversation. Often I end up rewriting full sentences and paragraphs. Sometimes I throw away large portions of text. I cut out filler words that add no value.

I like to do similar things with my code. I find this time ideal for writing tests. I already know how and what I am trying to build, yet I still have the freedom to refactor things, making them easier to test.

It is also a great time to rename variables and function names. During this time, I like to imagine myself reading my code for the first time. Can I tell what my code is doing?

I am not afraid of adding extra variables, if I think they will make my code more readable. At the same time I am not afraid of removing extra variables, that add no value.

My general rule of thumb is that a good name is better than a good comment, but a good comment is better than nothing: Names > Comments > Nothing.

Second pair of eyes

I do my best proofreading after I get some time away from my writing, but no mater how many times I review my prose I always miss something. My chances of having a typo-free prose increase exponentially with every person that gets to read it. (Special shout-out to my wife for proofreading my countless scribbles).

Same thing can be said about my code. That is why I find pull-requests and code reviews so invaluable. My reviewers are always able to find something that I’ve missed or give me a new perspective.

Fixing errors

My writing is never perfect. I always welcome feedback, both positive and negative, because it gives me a chance to do better.

Same is the case with software. While I try hard not to blow up a production database, I accept that I will make mistakes. In writing, I monitor what people are saying about my work. In code, I monitor what users are saying about my software and audit logs. I try to throw errors when unexpected things happen.

Conclusion

I couldn’t find a good parallel between a conclusion in prose and a conclusion in code. Perhaps someone can help me out in comments 🙂

I’ve read somewhere, that if we were writing code for computers we would write it in ones and zeros. Instead, we write code in high level languages, because we are writing code for humans to maintain.

I’d like to conclude with my favorite quote of all time.

Value this content? 🌟
Your $1 helps sustain our efforts.
Grateful for your support! 🙏