Raise your bus factor with coding standards and docs scrubs
For those just tuning in, over the past few weeks, I have been covering strategies for dealing with your team’s low Bus Factor – the number of developers who must be taken off a project in order for all forward progress to cease indefinitely. Startups and other lean development teams are especially vulnerable to a low Bus Factor. My team – MediaMath’s Apps Team – tends to work more or less independently building lean, single-purpose web apps and partner integrations, and we frequently find ourselves with a Bus Factor of less than two developers.
As a result, we have focused a substantial amount of time on ensuring our team on minimizing the risks of a low Bus Factor. In my post last week, I covered Legacy Code Lunch and Learns, the importance of an open door policy, and making domain knowledge reviews a standard practice. In today’s post, I’ll cover a few more mechanisms we have implemented to raise our Bus Factor.
Code Reviews & Coding Standards
To keep shared experience consistent, we do regular code reviews. We use two formats: Legacy Code Lunch and Learns (URL), and GitHub diff code reviews. Again the problem arises that we all work on independent code bases, each studded with design choices tailored to the needs of that project.
In light of this reality, we’ve started tracking team-wide coding standards. This endeavor is still in its early stages, but our aim is to create a point of congruence at which two developers unfamiliar with the particulars of each other’s projects can immediately engage in a valuable discussion about the merits and faults of a chunk of code. Over time, as every member of the team writes code according to the same set of expectations, our diverse code bases achieve a certain level of homogeneity, making it that much easier for a single developer to recognize and deliver value across the entire depth and breadth of our team’s output.
One of the most important, yet perhaps under-appreciated, means of achieving a reliable level of shared knowledge is regular pruning of documentation.
When systems only change slightly, updating documentation is often left behind. Eventually code bases change enough that the documentation is essentially useless, and updating it becomes a ticket (and an afternoon) all its own. Neglected documentation is useless at best. At worst, it’s destructive.
By way of self-defense, we make updating documentation a standard part of the code review process. Not all of our projects require robust internal documentation, so an eloquent manifesto is not necessary for each case. For the most part, we rely on (and enforce) self-documenting code, but there are a handful of projects that everyone knows are well-documented, so if the docs don’t show up in a major-feature code review, we know to ask questions.
More difficult than adding documentation is removing documentation. Of particular annoyance are comments in code — sometimes irrelevant, or entirely inaccurate, but kept around just in case.
Source control helps keep this clutter down, but it requires a somewhat ruthless spirit to really tackle it. A good developer is ruthless about removing unnecessary code, but this does not always translate to removing unnecessary documentation. There is apparently a certain amount of misplaced anxiety over cleaning up documentation, because it is seen to represent the system of record for a given project. In actuality, the only true system of record for a project is the code itself. Removing unnecessary code cruft can be an unexpectedly fulfilling act; this needs to extend to the documentation layer as well, or your project may become dangerously out of sync.
All this work and concern becomes worthwhile when, with minimal guidance from other team members, a new developer can jump into an existing project. More than just for new developers though, sharing knowledge and creating robust, regular code and documentation allows any team member to respond quickly, with confidence, to new challenges on old systems.