Signs that you’re slipping into Design Debt

Design Debt is one of the types of Technical Debt that you can work your way into gradually, usually without noticing. You might be keeping up with refactoring at the micro level, but at the macro level things have slowly gotten complex to the point of putting the brakes on momentum.

Recognizing gradual technical debt is made complicated by personal biases. As much as I trust my own instincts, I’m wary of firing off warning flares based soley on gut feel. It’s always possible that I’m the only one who is confused by some part of the system.

To reduce the effect of bias, I watch for the certain signs involving others on the team. Here are a few of them:

Estimation Spread. During iteration planning, when a team is estimating stories, a wide spread in estimates around a particular type of story might indicate that there’s lurking design debt. If the spread persists after you’ve discussd the estimates and the assumptions behind them in greater detail, you have a weak indicator of design debt. If a few people admit to being scared to take on the story because it means treading into code they don’t understand, you have a strong indicator.

Jockeying for Stories. If you’re on a team were any one (or any pair) should be able to pick up any story card, but you notice that there’s some gaming happening around a certain stories, such as the team manuevering it towards someone specific (e.g., the original authors of some area of code), you likely might some design debt in the form of specific knowledge in that persons’s head that hasn’t yet been converted into understandable code. The story may need to go to them now, but pair them up with someone who knows the code the least, and charge them with making sure that the resulting code is clear to both of them.

Depending on a Drawing. When you notice that others on your team have to refer to a diagram of some sort while working in an area of code, particularly when they are having to sketch out the diagram several times to get it comprehensible, that’s a good sign that design debt has built up. At the very least, save one of the drawings so that you don’t burn up time recreating it later. Comparing different verisons of the picture might also help point out what’s confusing (or just plain wrong) about the design.

Puzzling Tests. You’re progressing along steadily when a test a step or two removed from the action breaks unexpectedly. If you have to spend significant time puzzling through “what, exactly, is that test testing?” and other people on the team aren’t able to help, you’ve stumbled across test design debt. Test design debt can be nasty. Nobody really wants to spend time reworking an unrelated test, but disabling or deleting a test risks leaving a gap in test coverage. When this happens repeatedly in some area of test code, you have design debt to consider paying down. To avoid test design debt, take the time now to make sure that your tests are appropriately named, and either self-evident or well commented. Checking in a vague test is an invitation to trouble later.

As you notice signs of design debt, gradual or otherwise, take notes so that you have data that patterns might emerge from. At the very least, your notes will be good fodder for your next planning meeting or retrospective.