Advertisements are all good; the news is all bad

– Marshall McLuhan

This article summarises my thoughts, on why we often end up shipping terrible code, despite formally following all the good practices.

We will think about this in the next sprint

Agile software development presents itself as a set of perfectly fitted values, unfortunately, very little of them really help to improve the quality of the product from the engineering point of view. This bulk of healthy practices of customer collaboration and continious delivery does not really directly address any of the potential code quality issues that comes along. Sometimes it feels like this methodology is enforcing you to avoid this topic entirely, substituting it with a “pact with the Devil” grade approach. Instead of making bad code better, it makes bad code shippable. What’s even more pityful, the agile requirements can blur the lines between “good code” and “shippable code” so much, that developer teams can ship code for years, without even realizing how bad it is. Until it all suddenly crumbles. Sure, that the profressional software engineering communitty reacted to that with their famous and noble Software Craftmanship Manifesto, it is IMHO still too abstract to have a real impact on how software development (read: writing code) is approached in the world of Agile.

Peer-reviewed garbage

Relevant information is hard to come by. Soom it’ll be everywhere, unnoticed.

– John Cage

Despite being very important and useful practice, code review cannot solve the problem of “shippable code” by itself. In practice, code review can efficiently check the following:

• Some obvious errors, which were overlooked by the author and caught by a fresh pair of eyes
• Compliance to team’s conventions, readability and code quality standards
• Correctness of selected data structures
• Correctness of class structure and links between the elements introduced within the PR and nearby

What code review process often fails to achieve, is to evaluate how does this part of code, which might be cohesive and make total sense by itself, fits into the bigger picture: the project, the domain, the role, etc. Thus, it becomes very hard to prevent situation, where on paper (and in mind) you ship a perfectly fine piece of code, when in fact, you’re just throwing another bucket of garbage into a pile. Practical example: the PR adds some new functionality to a feature and it introduces a new service/utility class. But what if that domain already has 50 services? Can a peer reviewer confidently keep track on that?

Micro-services are not the answer

There is nothing we really need to do that is not dangerous.

– John Cage

The proposed solution for that would be the thing I call “architecture ownership”. Or “ownership of architecture”, this should be analogous to other agile jargonisms like “product ownership”, “feature ownership”, etc. Being an owner of a certain part of the project architecture implies having the answers to the following questions:

• What are the business objects? What operations are defined on them?
• What invariants do those business object have?
• What is the pipeline of presenting those objects to the cusomer?
• What is the biggest current code quality challenge, what pollutes code the most?

There is important omitment to be made here. You cannot have architecture ownership at the beginning of a project/feature, because in agile world, you, basically, not supposed to make architectural decisions at that point. Sounds crazy, huh?
It might be a good approach, to have ownerships of certain domains/feature stuctures and flows, once they have matured a bit. Frequently that comes alongside with heavy refactoring and code re-arrangements, but once you have those set, it will be much easier to detect undesireable distortions of architecture, when reviewing some PRs.

Certain architectural descsions, like invariant checking, strict typing, member visibility, final classes and methods can enforce some definitive patterns, so it will make sub-par OOP approaches if not impossible, then at least clearly visible even in isolated PRs.

But what do I do?

The way to loose our principles is to examine them.

– John Cage

Practical steps to introducing the concept of architecture ownership within an agile team would be the following:

• Identify a part of the product, that needs architecture ownership. Most often it is the one, that is the hardest to maintain, and constantly giving you headaches.
• Measure the test coverage of this part
• Try to determine what was the main reason this part of the project became unmaintanable. What kind of bad patterns accumulated there?
• Based on the previous observation, come up with new clean architecture, that enforces certain patterns
• Gradually move this feature/functionality to the new architecture, using previously written test as a backup
• Agree on a way of code reviewing the upcoming related PRs, that checks them for possible pollutions and misusage of current elements of the architecture.