What does the NYPD have to do with running a software project?
Recently my team have had the task of taking a new microservice from scratch to production. Initially with a fresh slate in front of me I got to thinking about a theory I first read about in The Pragmatic Programmer, “the broken windows theory”. First proposed by social scientists in the early 1980s it puts forward the idea that a community falls into downward spiral when seemingly trivial things are left unchecked, such as a broken window. The theory was notably put into practice by the NYPD in the 1990s to cut crime in New York. The Pragmatic Programmer puts the theory in the context of a software project likening broken windows to technical debt that quickly spirals out of control if left unchecked. In this article I’ll go through some ways we prevented tech debt problems from making it into source before they got a chance to turn into “broken windows”.
Code Reviews
Code reviews are great for many things including knowledge transfer and learning but perhaps most importantly they catch bugs. Agree a code review process with your team and enforce it with your tooling if you can. In the new repository we set up rules to automatically include the whole team on every pull request and required an approval as mandatory before merging to the master branch. We used the code review functionality included in Bitbucket.
The Build Pipeline
The build pipeline allows a consistent and automated way to build and package shipable code. It also allows us to add quality gates which will stop the new code reaching deployment or a master branch when standards aren’t met. Most of the other practices listed here can and should be incorporated into the build pipeline as gates and without doing so you can expect them to be quickly forgotten about if the team is met with a crunch to get code in in a hurry. Bamboo and Jenkins are two notable tools you can use here.
Linting & Static Code Analysis
There are many things a compiler or interpreter will let us do that we probably shouldn’t, this is where linting comes in. Linting and static code analysis allow you to enforce best practice rules to your codebase. Adding these tools to a project and as a stage gate in a build pipeline prevents less than ideal code reaching your master branch and saves time on code review comments. We used ESLint and SonarQube
Formatting
People have differing preferences when it comes to formatting and arguing about them during development isn’t exactly conducive to productivity. Agree a formatting style upfront with your team and apply a formatting tool to automatically format your files for you and enforce the rules in a build gate. We used Prettier which allows auto formatting and enforcing.
Tests
Tests serve many purposes; bug catching, documentation and influencing a cleaner design while practicing TDD. I’ve found it to be critical to add the tests as a stage gate in the build pipeline. We added the much touted industry standard of 80% coverage as a threshold for a passing build, something which on the path to production I was tempted to drop on many “crunch” days but in retrospect I’m glad I haven’t. We used Jest which has all the rich features you’d expect from a modern test framework.
