The GitClear "Debt Inspector" tool is built to sniff out where the tech debt is located within a repo. It will look something like this when visited under the top-level "Browse" tab:

Viewing a sorted list of directories where tech debt resides within the Facebook React repo

linkWhat is tech debt?

The term "tech debt" is generally used to describe any code that developers work in that is disproportionately time-consuming to maintain, or prone to causing regressions when modified.

An apt real-world analogy for "tech debt" is "a house with an old roof." You can still live in the house, but the longer you do, the more it leaks and the more you're getting dripped on. You can usually put out cups catch the drips when it rains. But some days, you’re too busy to empty the cups and the carpet will get wet. The “roof” in this analogy is “tech debt.” It’s not inoperable, but every day you let it linger without addressing its deficiency, the problem gets a little bit worse, and it generally hampers your ability to focus on other priorities.

linkHow does Debt Inspector detect tech debt?

Every commit made to a repo in GitClear is evaluated across many dimensions, including "how much did this commit change the repo?" (i.e., its Line Impact) and "how long did this commit take for its developer to author?"

Much like velocity in space is calculated by "distance traveled / time spent traveling," the velocity of code (its "Line Impact velocity") is "amount of change / time spent changing." Files that cause developers to sink in a large investment of time to effect a small change will be calculated to have a low Line Impact velocity.

For example, if Developer A spends one hour changing file bad/directory/main.cpp to beget 10 Line Impact, then the Line Impact velocity of the bad directory is "10 Line Impact per hour." What's the Line Impact velocity of bad/directory? If the only file in that path is the one we mentioned, then its velocity is also 10 Line Impact per hour. However, Developer B changes a second file, bad/util.cpp to gain 100 Line Impact in 30 minutes, then bad/directory would keep its 10 Line Impact/hour velocity, whereas the bad directory would now have a Line Impact velocity of (10 Line Impact + 100 Line Impact) / (1 hour + 0.5 hours) = 73 Line Impact per hour.

linkInterpreting Debt Inspector

Browsing tech debt within a directory of the Facebook React repo

Tech Debt Inspector uses the same columns as the standard GitClear Directory Browser, but the calculation of those column values differs in one very important way.

In the standard Directory Browser, each directory shows the Line Impact, Estimated Time Spent, and Line Impact Velocity for files in the directory listed, plus files in all of its subdirectories. In the Tech Debt Inspector, the columns evaluate only files that reside directly within the specific directory listed -- not files that reside in any of its subdirectories. So, in the screenshot above, the script/enterprise folder is listed as the second highest tech debt folder, but that estimate would not include any work that occurred within a file like script/enterprise/anotherdirectory/ That work would be accounted for in the script/enterprise/anotherdirectory directory.

linkUsing Debt Inspector to maximum effect

The Tech Debt Inspector uses a threshold of 60 minutes as the minimum time that must be spent in files in a directory for it to qualify to show in the Debt Inspector report. However, a CTO or VP of Engineering will often not be particularly concerned about directories that have only had an hour or two of work done in them over the past year. Usually, the directories that are having the biggest negative impact on a project's velocity are the directories that are being worked in every week.

Alternately, sometimes a Project Manager or CEO knows that a certain system in the code is going to be a focus of development during upcoming sprints. In these cases, it's useful to review the Debt Inspector to confirm that the directory where this work is going to take place is not one that has historically harbored low velocity work. If the directory where the change is to happen tends to be among the lowest-velocity directories in the project, that suggests that an effort should be taken to remove or refactor the directory prior to beginning additional work in it.

The best path when you're getting acquainted with your repo's tech debt is to hone in on the directories that are both low on "Line Impact Velocity" and high on "Estimated Time Spent." That is, look for the directories where the "Estimated Time Spent" bar is filled up, and start by focusing on those:

The vendor/gems/stat_master/jobs directory is arguably the best target to look for tech debt reduction, given that it has both a low velocity and a relatively high amount of time spent in it

linkGetting more details about slower-than-average work

Once you find a directory that you'd like to better understand, you can click on the directory to see which files within it are contributing to the low velocity:

Files in Tech Debt Inspector are sorted by which have the lowest velocity. In this case, generate_impact_csv.rb looks to be the single biggest maintenance headache in this directory

Then you can click into a file to see the slowest commits that have happened within your selected time range:

Viewing the commits that contributed to a particular file being designated as "low velocity"

If you see a commit that seems amiss (unreasonably low Line Impact, or unreasonably high "Estimated Time Spent,") then any user with the permissions to edit Line Impact or Estimated Time can click into the commit link and adjust those quantities so that a file or directory no longer gets a bad rap for being slow to evolve.