Packetizer Logo
 

Writing Code for the Next Person

By: Paul E. Jones

Introduction

Having spent years in the software industry, from nimble startup companies to established tech giants, I have seen a wide array of coding styles, commenting preferences, and varying degrees of code quality. Over time, I learned what did and did not work well for software teams. I often saw choices made by teams that had a negative impact on productivity, code quality, and sustainability. It was those choices that motivated me to give talks, push for changes within my teams, and to produce this document.

Code Snippet
Code Snippet

Relatively early in my career, I joined a startup company that presented me with a manual containing coding style guidelines, commenting guidelines, etc. Initially, I thought it was arduous to write code adhering to those guidelines. However, it did not take long before I grew to appreciate them. The reason was that it made it very easy for me to grab anyone's code in the company and immediately use it without wasting time reading through the code to understand it.

Later, I joined a big tech company based in Silicon Valley. After having spent the past few years blissfully writing code with a consistent style, good documentation, etc. it was a hard smack in the face when my first project at the tech giant was on a massive legacy code base with virtually no consistent style or documentation.

As I progressed through my career, I noticed that this kind of haphazard coding practice was pervasive in the industry, both in open source and closed source. If one dared to ask how something worked, the reply was often "read the code." That's a very dissatisfying response, and spending time reading code one will not be changing has a negative impact on productivity.

Teams should be writing code for the next person. After all, virtually every project, from the smallest prototype to the largest complex system, will most likely have people joining the team to carry the product forward long after the original authors are gone.

In the various subsections of this document, I will explore a few topics that I believe will help lead to higher productivity, fewer bugs, and better overall code quality.