What is Technical Debt and Can You Avoid It?

Posted on May 6, 2019 by in WordPress | 6 comments

What is Technical Debt and Can You Avoid It?

If you’re in software development, you are going to have to deal with technical debt at some point. So to answer the question in the title…no, you can’t avoid it. However, there are steps you can take to minimize its effects and make sure it doesn’t get out of hand. At least too badly.

What is Technical Debt?

Tech debt, as it’s sometimes called, is essentially the cost you incur over time for having imperfect code. Changes and updates to the source code have a cost, as does adding a new member to the dev team, adding a new feature, or fixing bugs and patching exploits.

As your project gets larger, the codebase expands, and more people work on that code, their voices and styles will clash here and there. Maybe you have a deadline and a less-than-ideal solution is patched into the source code to finish on time. Perhaps you add in an open-source component you don’t fully understand to handle a feature instead of coding it yourself. Or you could switch libraries between versions (from Backbone to React, for example), but still need to support folks using the legacy codebase for their projects.

Absolutely none of these things are bad. Not on their own. Maybe not at all. But when added together, the technical debt they incur is going to have to be paid back at some point in the future.

At some point, that open-source component may need to be replaced (or forked). That will cost time and money. In the distant future, you’ll need to remove all of the Backbone code from your project and stop supporting legacy users. Again, time and money. That patch you did to meet a deadline? Well, it will eventually come undone and need a more permanent fix. Time and money. And you’ll have new members of your team who go back through old code to do all this, needing to understand previous devs’ code and logic. Time. Money.

You get it.

While technical debt is an abstract term, often metaphorical, the cost of tech debt is very real. Paying it back has a monetary value, and you can track the interest you pay on it in work-hours and paystubs. You can see it in the bottom line of all software development.

Can You Avoid Tech Debt?

Like I said before…not really, no. You are going to accrue technical debt in every project you write if you ever go back to the code after its release. However, if you break down the types of technical debt, you can minimize and even account for it in your projects. If you consider the debt beforehand, it’s no different than taking out a car loan or a mortgage. You look at the cost, the interest, and the benefits, and then you decide if you can/want to pay it.

Let’s take a look at some of the examples we discussed above and see if there’s a way to avoid, minimize, or absorb the cost.

Considering Purposeful Technical Debt

When we say purposeful technical debt, what we mean is that your team has made decisions that you know are not within the so-called best practices for either the language or type of project your working on. We mentioned earlier that you might have a deadline to meet. And maybe that deadline is hard and fast. Maybe there is a 0% chance of it being changed or shifted.

This is when you need to consider taking out a loan and going into technical debt.

You really have three options here:

  • Put out software that is unfinished and buggy, but you make no concessions for code clarity and logic
  • Pull features you can’t manage to perfect, but release what you have that’s as well-written as possible
  • Make development decisions that put out “good enough” code to get everything running, but will likely need to be addressed again later

The third option here is often the one people choose. That’s going into technical debt. And there’s nothing wrong with this. Because you made the decision to do it.

Paying Back Purposeful Debt’s Loan

Make sure you document the decisions behind the choice to go this route in your code. Keep notes on what you did versus what the ideal solution would be. And make sure that you include at least some kind of commentary in the source code to indicate where this debt-taking solution was implemented (and if you know, affected systems in other areas of the project). If you don’t take this step, adding to the project (even in bug fixes and patches, not to mention new features or an expanded codebase) can be horribly delayed by finding a patchwork solution when you expect a complete one.

Again, that patchwork solution might be perfectly fine and never give you any real problems. But the technical debt is still there and needs to be accounted for.

Considering Legacy Code Technical Debt

Another common kind of technical debt is one that WordPress is accumulating a lot of right now. WordPress can run on PHP 5.x. The newest update, however, will tell users that it must at least be PHP 5.6. By the end of 2019, the WP Core will require PHP 7.x. However, by pushing the requirements up, a lot of old code has to be updated. Because there is still PHP 5.x code in plugins, themes, and Core itself.

Not to mention the new Block Editor. It’s written in JavaScript. React, specifically. That’s nothing near PHP. In fact, much of the WordPress Core is being re-written into JavaScript, little by little. But all of that JS has to compliment and get along with the PHP, too. Taking on new technology is great, and adopting new versioning requirements is necessary. But in doing so, you’re paying interest on the unavoidable technical debt you incur from that software having been in existence for a while.

Paying Back Legacy Code’s Debt

This one’s kind of tough because there’s not a great way to do it. You could take the nuclear option and do a complete rewrite from the ground up in the new language/framework/version (look at what we did between Divi 2 and Divi 3.0, going from Backbone.js to React). This still doesn’t entirely fix the problem of the debt, however, as you still have people using the old library. At some point, you will have to drop support for the legacy codebase. Which is kind of like paying back the loan. Until you have to take out the next one.

If that’s not an option (or the best idea for you), you can make sure that you don’t rely on language- or version-specific features. Front-end developers have to deal with this all the time, as some browsers support brand new features quickly, while others (Microsoft Edge/IE, cough cough) might never adopt it. You can future-proof your projects by sticking to the basics, which will, in turn, make the number of changes that need to be addressed when upgrading or refactoring fewer than they would be otherwise.

Considering Multiple Developers Over Time

This is a kind of tech debt that large teams tend to accrue over time worse than small dev teams. Though even small ones need to worry about it, too. You see, every software engineer writes code differently. Very rarely will you have two devs that solve the same problem with the exact same code. They may perform the same function, and the end result might be the same, but the code will be written in the voice of the author (just like you can tell who wrote posts here, for instance, as Jason, Nathan, Donjetë, and I all have distinct styles). Code is no different.

Keeping that in mind, the logic can sometimes have different voices, too. What one dev thinks is perfectly clear, another dev will look at and have no idea why the code does what it does. This issue becomes truly problematic when the original author is no longer available to consult. The technical debt accrued by this can be catastrophic. But there are ways to handle it.

Paying Back Old Devs’ Technical Debt

The easiest way is to hire the best devs possible and never let them leave your company. Ever.

Since that’s going to not happen around 100% of the time, paying back this debt can be mitigated a little easier than you may think. First of all, make sure that you train your dev team to comment their code. And to comment it well. Whenever they make a decision that might even remotely be considered ambiguous by someone else, have them note why they did it and how the function works.

Additionally, make sure that every dev on your team sticks to a style guide or set of standards. The WordPress Core has a set of coding standards that will keep plugins, themes, and Core contributions inline so that anyone else coming later won’t have issues with it. Airbnb has a style guide for React that has been adopted as an industry-wide unofficial standard. Even internal style guides and standards keep your devs from going too far on their own because those kinds of commits won’t be merged unless they’re up to snuff.

Wrapping Up

Technical debt is a very real problem. It’s also a very real resource if you know how to manage it. By being able to decide when you take on tech debt and how you pay it back, your development can go quicker and smoother than otherwise possible. And in those times when taking on that burden is unavoidable, we hope that we’ve given you some ideas of strategies that you can implement to make it less impactful than it might otherwise be.

How do you handle technical debt within your projects and dev teams?

Article featured image by Andrey Suslov/ shutterstock.com

Check Out These Related Posts


  1. Hi BJ,

    The idea of technical debt gets interesting when you mix in the nebulous concept of disruption. In context to the addition of the block editor in WordPress, it has been intriguing to watch how various theme and plugin vendors respond to this. Where third party integrations have been developed to work nicely with Div, I now see some divergence in how each deals with the new layout paradigm of the block editor.

    The big falling between stools of the new editor is the lack of provision of proper layout elements (section/row/column). They got as far as a half baked column block and gave up, leaving the work to a slew of third party plugin vendors and leaving the page builders out in the cold with their own proprietary system of shortcode and markup systems.

    The big elephant in the room here has been a missed opportunity, much needed for a long time in the WordPress community; MISS (Make It Standard Stupid). Providing a basic foundation in Gutenberg with layout elements to which third parties could hook in their own interfaces with bells and whistles would have made the technical debt of transition so much more bearable. Switching theme or builder could leave content intact in the layout intended.

    • B.J. Keeton

      I am sincerely hoping that as Gutenberg and the Block Editor become more fleshed out and integrated as a theme builder, we will see those kinds of hooks added in for more seamless transitions like you mention.

  2. So helpful to have a term to associate with coding risks – rather than just telling clients that demands, mostly around deadlines, may end up costing more down the road.

  3. In typical IT language, we term it shortcuts. And shortcuts never result in longlasting success. Technical Debts are inevitable sometimes but it is more of a mind game. Patches and open-source components may be demand at times, but one has to be determined to fix it with their own component in a timely manner. Most of the times, people don’t touch things if they work. But they forget that if it breaks, it will need a lot more time and money to fix.

  4. I find technical talk hard to understand thank goodness I found your site. Its interesting to look at it from both sides.

Leave A Reply

Comments are reviewed and must adhere to our comments policy.

Join To Download Today

Pin It on Pinterest