Why you should have a TECHNICALDEBT.md in your repo
If you’re a developer with at least a couple of years of experience, you must have been there: a sudden business need appears that has to be fulfilled quickly. You are asked to add a new feature or make a change, but you don’t have much time.
You know there’s a proper way of doing it, but you’re looking for the quickest solution. You suggest a quick and easy, but “hacky” way to solve it. Your client or boss agrees to it, and you implement it in your code.
This is one of the many ways “technical debt” is created.
Technical debt is a concept in software development that refers to the extra development work that arises when code that is easy to implement in the short term is applied as opposed to implementing the best overall solution. This can make it harder to make changes to the code in the future, and it can also make the code more difficult to understand.
This can result in many headaches: developers may have to spend more time and effort working on the code which can slow down development and increase the overall cost of the project. It might also take longer for new team members to understand the code and all its quirks.
The problem is if we don’t keep track of these changes, even if we document our code properly, things can quickly get out of control. When other developers in your team, especially new members, go through the code, they’ll only learn about some of those implementations once they see a comment, and maybe use git blame to see which commit added the change.
A way of solving this is keeping a TECHNICALDEBT.md file in your repository.
Why keep a TECHNICALDEBT.md?
A single source of truth regarding technical debt can help developers in many ways.
First of all, it’s a quick way for other team members to learn about potential quirks or unusual solutions they may encounter while working with the code base. Why is this bit hardcoded? Why is this function repeated multiple times? Why is this bloated library being used? Those questions can be easily answered by learning about the history of those changes. Such a file gives additional context alongside inline comments and git history.
Secondly, it encourages developers to address the debt, improve the solutions and then remove the item from the markdown file. If the file keeps growing, it gives you a justification to allocate some time to finally address those problems. If the project you’re working on is open-source, it might give new contributors ideas what to work on to improve the project.
Finally, it increases the general awareness of the concept of technical debt, which can hopefully encourage teams to make better decisions in the future. It is sometimes necessary to introduce technical debt, as certain circumstances may make it unavoidable. However, making recording technical debt as part of your process should encourage everyone to also make reducing technical debt as part of that process too. It is crucial to not leave those code changes unattended, and always have a plan of how to deal with them once more time is available.
Example structure
Here’s how you can structure your TECHNICALDEBT.md file:
### Change name
Description of change and justification behind it
#### Commits
* [commit hash 1]
* [commit hash 2]
* ...An example entry for a web project could look like this:
### Hidden pages
Some pages are hidden. The list of hidden pages in the form of slugs
is hardcoded in a variable in `constants.ts`. Once there is time to
implement hidden pages as part of the CMS, this variable can be removed.
#### Commits
* a8c78d71
* 6d3cff11This gives you all the information you need: what has been done, how it affects the code, and which commits introduced the changes.
You can see the commits by using git show [hash] in the command line, which will show you all affected files. This is especially helpful if since then more changes have been made, so you can see how the initial change was implemented.
Obviously, you need to update the file in a separate commit, as you don’t know the hash of the commits until they are created.
Create your TECHNICALDEBT.md file today
I encourage everyone to start using such an approach to handle technical debt in a better fashion. You can still use comments and TODOs in your code, but having one centralised place will help you prevent headaches in the future, and make your code more manageable, especially for people who are new to your codebase.
However, one thing to remember is that technical debt can take many forms. Sometimes engineers can create technical debt when making infrastructural decisions, for instance which hosting solution to use, how the CDN or load balancer is setup, and so on. Keep an eye on these things to save yourself time and effort in the future.
Maciej is a full stack developer at Good Praxis.
