This is part of a series called Eight Questions to Ask About Your Tech Debt
The main thing to keep in mind is this diagram (described in the introduction):
The next question we’ll cover is on Misalignment: If this debt were paid, how much more would our code match our engineering values?
In Chapter 21, I talk about the importance of maintaining a style guide for tech debt. I think most of use some kind of guide to make sure we use the same indentation and naming conventions, but you should go beyond that. One important addition I suggest is to describe your target architecture. In a long-lived codebase, you sometimes see older code that doesn’t match the way the team currently does things. Describe the ideal and under what circumstances it’s ok to update old code.
The main goal is to reduce the number of comments on a code review that are (just) opinions. Comments like that should either cite the style guide or start a conversation (outside the review) to add to the guide.
Let me give you two examples. The first is something highly misaligned and the second which is not.
A High Misalignment Example
On the iOS team on Trello we had agreements that new code should be written in Swift, but also that it was ok to rewrite Objective-C code as Swift before a major change. The agreement meant that any PR that started with a conversion of some code to Swift was ok, and that new Objective-C code was probably not.
It also meant that all old Objective-C code was misaligned. So, any tech debt project that would result in that code being converted might get more support from our team. We felt the same about UI code that was not written as Model-View-ViewModel (our accepted choice).
Many teams might have a code coverage requirement. If so, code with low coverage has high misalignment and adding tests would bring that code more into alignment.
A Low Misalignment Example
There are two ways to score low on misalignment.
The first is if there’s just no documented agreement on what the team’s opinion is. I scored the items above high on misalignment because they violated an agreement. The same code would score low without it.
But, also, there’s code that could have plenty of issues, but fixing them won’t fix an alignment issue. In yesterday’s email, I talked about fixing a highly visible Markdown issue. That issue would score a 0 on misalignment though. Our code was just a trivial call to a 3rd-party dependency (which was fine). The issues it had (not working in edge cases) didn’t violate our style guide.
If Misalignment is Low, Add to Your Standards Documentation
If you have a tech debt project that can’t get support on the team, and it’s neither visible or misaligned, one thing to try to do is see if you can get the team to make an agreement about it. If so, then maybe this problem will get higher priority in the future.
For example, yesterday I talked about projects I worked on that had 100’s of compiler warnings. I tried to address this by getting the team to agree that warnings were unacceptable. Unfortunately, that didn’t work, but if it had, we might have been able to get a project going to fix them all. (I did make progress a different way, which I’ll talk about tomorrow, because it’s related to the next question).
Next: #3 Size