Technical Debt Program

Overview
The Technical Debt Program has been put in place to help the Foundation and the broader community better understand and manage MediaWiki technical debt. This article's purpose is to help establish a common understanding of technical debt and document a process by which the Foundation and community can: The Technical Debt program is actively managed by the Code Health Group.
 * identify it
 * avoid incurring more of it
 * manage it
 * reduce it

What is Technical Debt and why is it important?
As put simply by Dan Rawsthorne - "Technical Debt is what makes code hard to work with."

Although simplistic, the spirit of the above definition is generally at the core of most industry experts’ own definitions.

The reason it’s important is because code that is hard to work with generally hampers developer’s productivity and results in less stable code.

If it’s so simple though, why say anything more? Well, because it seems like all too often the term “technical debt” ends up being applied to a wide range of issues, and as such, becomes unmanageable. Technical debt is NOT a bug or the lack of a feature. Technical debt is not just a fancy name for “sloppy code”.

Technical debt is generally not visible to a user of the system. It’s visible to developers and those that have to work with the source code in some capacity. Although defects themselves are not technical debt, they can be a result of technical debt.

Taxonomy
I. Debt incurred unintentionally due to low quality work

II. Debt incurred intentionally

II.A. Short-term debt, usually incurred reactively, for tactical reasons

II.A.1. Individually identifiable shortcuts (like a car loan)

II.A.2. Numerous tiny shortcuts (like credit card debt)

II.B. Long-term debt, usually incurred proactively, for strategic reasons

Is Technical Debt Bad?
Well, it depends. Often we are faced with the decision to take a shortcut in order to get code deployed faster or make progress in another area. Those shortcuts have a future cost, not unlike real debt. Do the short-term benefits of the shortcut outweigh the long-term costs? If so, it might be worth it. But as with any debt, accrual of the debt without plans to repay it is a bad idea. It leads to ongoing “interest” payments in the form of slower progress whenever working in that part of the code. So, if you consciously make a decision to incur the technical debt, do so with a plan to repay it as soon as possible.

Looking at the aforementioned Technical Debt Taxonomy, types I and IIA.2 should really be avoided at all costs. They generally don’t result in any near-term advantage and are generally difficult to track.

When deciding whether or not to take on technical debt, make sure that your stakeholders are involved in the decision. They will not only know what to expect in the near term, but also be able to support refactoring work later.

Reality-Check:  How often do you really get a chance to go back and refactor things once the code’s been deployed? Generally speaking, if it takes you longer to document the technical debt than the time/effort saved, it’s probably a bad debt to incur.

In-Practice: Once you’ve decided to add more Technical Debt, enter a task in Phabricator tagged as “Technical Debt”. The task should describe the debt that was added and why it was added.

Removal (paying off debt)
Removal of technical debt is focused on the overall reduction of existing technical debt. Within the MediaWiki ecosystem, we have a large existing codebase with an undefined amount of technical debt. This existing technical debt may or may not be impacting our daily efforts. How do we find it and determine if it needs to be removed?

Patterns to look for are: Generally speaking, those that work on the code gain a pretty good understanding of those areas that are hard to work with. They may even have some ideas as to how to make it easier to work with.
 * An area of code that people avoid at all cost due to fear of breaking it or general lack of understanding.
 * An area of code that seems to break often.
 * An area of code that is developed and maintained by a single person (because they are the only one who understands it).

Once areas have been identified, what then? Prioritizing the work can be challenging and often results in the “low hanging fruit” approach. All things being equal, the LHF approach isn’t a bad one. When you have equally impactful areas that need attention, choose the easiest ones first. However, all too often, impactfulness is not factored in when selecting the LHF. As a result, a bunch of work is done (tasks completed), and people feel good about the shorter list, but the actual impact is marginal.

For that reason, impact should be the primary criteria when prioritizing the removal of technical debt. For example, if there’s an area of code that is routinely modified vs an area of code that is changed only once every 3 years, the impact of removing the technical debt from the prior is probably more impactful. This is perhaps an overly-simple example, but it does demonstrate some of the factors to consider.

Once the areas are identified, the work at hand needs to be identified. To that end, sound design and implementation principles should be followed or one risks removing some technical debt while introducing different technical debt. For that reason, it’s important that all that contribute to MediaWiki employ sound software development principles. The Code Health Group, a cross organizational group responsible for defining these principles, is a good place to start.

In-Practice: All too often developers go into refactoring efforts with the expectation that nothing will break. However, the reality is, things WILL break. As with any other development, having adequate tests in place will help manage the breakage. Don’t be afraid to break stuff, expect it.

Avoidance (not incurring new debt)
Where removal focuses on the reduction of technical debt, avoidance is about minimizing the introduction of any additional technical debt. As noted previously, technical debt isn’t necessarily bad, provided it’s a conscious decision with well understood benefits and costs, and a plan to remove it at a later date.

Avoidance is made up of two distinct parts - knowing how to design and implement a debt-free system, and understanding when to incur technical debt and when not to.

Knowing how to design and implement a debt-free system is outside the scope of this post. Please see Code Health for more resources on that topic. That being said, example are: code complexity, coding standards, and test coverage.

Equally important is when to make the decision to incur technical debt and when not to. The following is a diagram of a decision tree to help make a good technical debt decision.

Key points from the diagram:
 * Don’t incur the tech debt if it takes longer to discuss and document it than to take the more desirable approach.
 * A lot of small shortcuts are difficult to document and track.  Over time, they will crush productivity.
 * Although discussing tech debt decisions with peers and your direct engineering manager may be enough for tactical short-term tech debt, longer-term strategic tech debt should also be discussed with the Product Manager and Tech Committee as the impact of the tech debt may be broader.