Code quality analysis comes in all shapes and sizes. From empirical measurements to heated discussions, expressions of code quality can vary from team to team, person to person, or even an individual! I had an experience lately regarding how one judges quality, and it goes beyond anything you can measure, analyze, or generate in an automated fashion. It focuses on a metric that’s agnostic to implementation detail or tech stack: Ease of change.
How Easily Can One Make Changes to the Application?
Now, you can technically measure this, if everyone on the team is diligent about recording time spent on tasks. You could then get statistics on the figures and watch the mean time to change over the lifetime of an application’s development. But here I’m largely focusing on personal experience when working on one application, then another, then comparing how easy or difficult it was to implement a change. Sometimes time itself can be a red herring, when making changes otherwise feels smooth and easy. Some other “objective metrics” may go out the window here, but that’s okay!
A Real World Example
Let’s run through a change I made recently to a real world application: An entity needs a new field. This means the database should be updated to have the new column, and all interactions with the entity should take this new field’s existence into account. How easily can the change be made? How confident are we that the change being made will work, without breaking existing functionality?
As I implemented this feature, something struck me: Despite a potential code smell lingering (which I’ll get to in a moment) I found making this change to be a breeze! The database schema was controlled via code first database migrations, so “updating the database” was a non-issue: Update the relevant entity with the new field, generate the migration, and we’re done. On the code side of things, it was a matter of tracing back where the entity can be created or updated or read, and making sure the new field is correctly hydrated when taking those actions.
This last part resulted in quite a few files being changed. Uh-oh, sounds like a ding against quality here! Perhaps counterintuitively, this is fine! Why? Because I didn’t have to think about all these files or stress over the amount of literal code changes being made.
Don’t Make Me Think
The first step (completed earlier) was updating the entity: A new field (string type in this case) to be set on creation or update, and retrieved on fetch. In this application we’re making heavy use of Command Query Responsibility Segregation (CQRS), so the points of interest for me are:
- Any Queries fetching the entity
- Any Commands creating or updating the entity
- Any tests surrounding these classes
Updating the entity broke most of these. The bulk of this update was not having to manually track down changes and assure everything worked by just running the application through all the scenarios. I “leaned on the compiler”, i.e. the compiler told me precisely where to make my changes. An easy, automated TODO list that guided me through the application, making the changes a breeze despite the number of files touched.
At the end of the day the pull request containing this change had about two dozen files touched. One might balk at that figure at first blush: You had to change two dozen files just to add a new field to an entity? That must mean the code quality of the application is poor! But I contend that context absolutely matters, and that “lots of files changed” does not automatically downgrade the quality of an application.
The above series of changes, two dozen files, including migrations, entity updates, command/query updates, and test additions (which help assure the changes are golden), took all of 15 minutes. That time included running the application for real to verify all was well! More importantly, while some thought process goes into any change made to an application, I by-and-large didn’t have to think about the multitude of code changes made to implement this.
The concept of spreading out an application’s code across so many files, divisions, and rules represents a shift I’ve seen through most of my career: A multitude of small files sounds difficult to maintain and read through. But with the advent of better tooling (either native IDE functionality or addons/plugins to accelerate code navigation) and philosophies such as the Single Responsibility Principle in play, what seem like obstacles end up becoming accelerants to one of the most important (in my opinion) metrics regarding code quality: How easy can you make a change? And, more importantly, how hard do I have to think about said change? What’s the overall turnaround time on implementation, testing, and assurance all is well?
If the answers to those questions are “it’s not so bad”, then maybe we leave behind the assumption that “many files touched to make a simple change means code quality isn’t so hot.”