In software development, it is crucial to maintain code cleanliness and quality to ensure that a project remains easily maintainable.
However, in daily work, developers often face the need to solve tasks quickly, leading them to leave comments in the code such as TODO
or FIXME
for future improvements.
Over time, the project becomes overloaded with unfinished tasks. These comments accumulate and transform into invisible technical debt, which can negatively affect the project.
The Problem with TODO
Comments
Initially, such comments serve as reminders of areas that need further work or refactoring. For example, it might be necessary to optimize an algorithm, fix a temporary solution, improve code readability, or replace an outdated API. However, under tight deadlines and shifting priorities, more attention is often given to the "real" tasks in Jira, Trello, or GitHub Issues.
TODO
comments can remain in the source code for years. Over time, they tend to be ignored, often due to changing priorities or team composition.
But every such comment is a debt that needs to be repaid. The more debts there are, the harder it becomes to manage technical debt.
So, what problems do TODO
comments bring:
-
Invisible Technical Debt: Accumulation of
TODO
comments creates an illusion that the codebase is in order, while in reality, it hides potential problems. - Decreased Code Quality: Unresolved tasks lead to bugs and difficulties in maintenance.
- Loss of Context: Over time, developers may forget what exactly needed improvement, especially when the team changes.
What Can Be Done?
Technical debt is almost an inevitable part of the development process, but it is important to manage it so that it does not become a serious obstacle. To achieve this, you can conduct a review of comments during code review, integrate tasks from TODO
comments into the project management system, and regularly reassess priorities.
Regular refactoring and a conscious attitude towards TODO
comments help keep the codebase in a healthy state.
To analyze this problem, I wrote a utility called Todoctor, which helps to examine debts and control their accumulation.
How Does Todoctor Work?
Todoctor is a CLI utility that processes and analyzes TODO
comments in JavaScript and TypeScript code, tracks the history of these comments, and generates a report in HTML format.
Based on the collected information, Todoctor generates a graph showing how the number of TODO
comments has changed over N months.
This visualization motivates the team to take action, providing specific metrics and allowing progress tracking in reducing technical debt.
In addition, supplementary information is provided:
- The age of the oldest
TODO
comment - The total number of
TODO
comments - The average age of
TODO
comments - The name of the author with the highest number of such comments
Also, there is a sortable list of TODO
comments in your project:
To use this tool in your project, simply run the following command in the root of the project:
npx todoctor
After some time, you will receive a generated report on your project.
Conclusion
Technical debt may seem like a minor issue until it starts slowing down development and degrading product quality. TODO
comments are often overlooked, but like any debt, they will eventually need to be paid off.
Todoctor: https://github.com/azat-io/todoctor
Top comments (0)