Dark Corners of Our Code - The Impact of Technical Debt - Part II

What leads to unmanageable pieces of codebases


Sep 26, 2022

Dark corners of code
Photo by Charlesdeluvio on Unsplash

Technical debt doesn't just eat away at productivity because of a series of specific technical issues that impact a codebase's health. Knowledge sharing, refactoring practices, and structural coding decisions all influence how productive our teams are able to be. And unfortunately, the way different teams approach these issues often lead to them having sections of their project that no one on the team wants to touch. Let's take a look at how common these untouchable pieces of code are, and what cause them to occur.

This is the second part in our series on the current impact of technical debt based on our latest survey of technical debt's impact on softwre engineering performance. Read the first part here.

Want to contribute to the survey? Take 2 minutes to answer here

The dark corners of a codebase

Most of us have worked on a project at one point or another in our careers where there's a section of the codebase that no one wants to touch and where, quite frankly, no one really knows what's going on. Unfortunately, this is more pervasive than we would all wish it to be.

Amount of teams with untouchable code

Roughly two thirds of the teams that we surveyed reported that there is at least one section of their codebase that no one on their team wants to touch. Even more shocking, these sections of code are often mission critical to what the project is trying to do. For instance, one respondant said that one section of their code was:

A single line of code that nobody knows what it does, but once you remove it, everything breaks.

This might be an extreme example, but distressingly, the critical nature of these untouchable sections is all too common. 30% of all teams who reported having an untouchable section of their code said that it handled mission critical piece of their project.

So how do we keep winding up in this place?

Knowledge sharing, a human and documentation failure, and the causes of untouchable code

A project doesn't develop a section of it that no one is comfortable working with by chance. Over and over again, the same set of issues led to teams being uncomfortable working with a piece of their project. The most common issues were:

Failure to share knowledge and sufficiently document (34% of teams with untouchable code)

We have to support it because it's business rules engine. But, all the people who knew about it, have left the team.

The most common reason teams wind up with a section of their code they weren't comfortable touching is really a failure of a team's culture itself. As team members come and go within a project, oftentimes the developer responsible for a certain section of the codebase no longer works on it, and sometimes is no longer involved in the project at all. When teams don't share that individuals knowledge, either through direct conversation and knowledge sharing or by having sufficient docs they run the risk of having an untouchable section of their codebase.

Not refactoring code as it grows (31% of teams with untouchable code)

(It's become) layers and layers of code one on the top of the other, instead of rewriting them as a cohesive whole

A section of a project can become untouchable, even if it was originally well maintained, if we're not sufficiently refactoring it as we go. When new code keeps being added on top of more and more layers of existing code then it creates a critical level of complexity that becomes unmanageable. Typically this can be headed off by refactoring this section of the project, but if we never get around to that then the code can become completely unmanageable.

Technical and structural decisions (21% of teams with untouchable code)

It's just a complex and highly unconventional use of Python

Technical decisions can have a critical impact on whether or not code is maintainable. If we continue to add to a section of a project until it becomes critical, but chose a fundamentally wrong technical structure and approach for a project and for our team when setting it up, then we must continue to support it, but won't really be able to manage it.

Sometimes an unconventional solution (or a magical one) might seam like a great idea. It can accomplish a specific goal in a novel way, but it can also lead to these maintenance issues down the line. If we do need to take an unusual technical approach we need to take extra care to make sure we're sufficiently documenting everything.

Age doesn't matter

You might think that issues of unmanageable and untouchable code are just issues in decades old code. But, across all the teams we heard from in our survey, there is not a major difference between teams with old (10+ year) code bases and teams with young (<5 year old) codebases. Teams with codebases that are in an in-between age had less issues with untouchable code, but that may just come down to a respondant volume issue. Either way, teams at all stages of their lifecycle should be paying attention to ensuring that their code is well maintained and doesn't start to develop untouchable corners.

Frequency of untouchable code by codebase age

Keeping a codebase manageable

One of the most dangerous types of technical debt is having a section of your project that no one on the team is comfortable working with. It leads to slower development, makes new feature development riskier, and significantly drives up bug risk. But, by making the right initial technical decisions, refactoring as our projects grow, and making sure we have a process in place for documenting our code and sharing our knowledge, then we can help reduce the risks of untouchable code emerging.

Are you looking to reduce your tech debt or prevent it from building up in the first place? Learn how Sourcery can help your team improve all your Python code and ensure it's following your team's best practices.