Conventions, conformity, and code review

[ahmedk92]

Conventions, conformity, and code review

I think every other software team now has a set of code conventions to achieve a high level of consistency, which is enforced by a strict code review process.

Consistent code is a joy to work with. It makes sense to make an effort to maintain a high level of consistency in the codebase. However, my argument here is that at some point, clinging to this high bar of consistency can impact productivity. This impact on productivity usually takes the shape of contributors having their pull requests stuck for days, and code owners spending significant time and effort doing police work. Once this becomes a trend in a team, I believe it should be everyone's top priority to eliminate such waste.

Usually, addressing such issues starts with trying to fix this from the contributor's side. Maybe the conventions are not well-communicated? Maybe we need sessions to explain things? Some even consider relaxing some rules. But it's rare to rethink having conventions in the first place.

I can imagine some readers gasping already (and some consultants fainting) when reading “rethink having conventions”. This isn't a rant against conventions though. On the contrary, this is more of an acknowledgment of defeat (as a person who likes code to be consistent) against simple reality. Having one set of conventions to flawlessly rule the constant stream of code asking to be merged daily by a large team seems to be too idealistic. One needs to make compromises here. It was painful for me to witness software teams prioritizing such consistency over shipping that led to constantly missing deadlines.

When teams get that large, they often think of modularization. Be it a multi-module mobile app or a microservices-based architecture, it makes sense to break down things into smaller pieces to facilitate parallel and isolated development. Much of that gain is reversed anyway by installing a bottleneck-like step of code review that makes sure every piece of loosely related code conforms to the same rules and conventions. And worse, such a process is enforced by the same small set of code owners.

Modular architecture depends on APIs. APIs are typically a thin crust of each module. I don't see value in enforcing the same rules and conventions on any code that is not an API. Instead, there should be a minimum shared quality standard. Things that affect security and performance, and not architectural preferences and style.

One caveat of my suggestion is it opens the way for fiefdoms. This is a valid concern. However, I think it's a reminder that software development is a live human activity. I don't think there's a recipe that we can blindly follow without constant monitoring and reevaluation. But I think it's more reasonable to just watch out for such issues if the signs start to show rather than pay a huge cost upfront.