Never Forget a TODO Comment with tickgit, Your Repo’s Project Manager

tickgit is a command-line tool and web application that helps developers do project management in their code, through the use of TODO comments and other plain-text markers. It’s a low-overhead way of managing your backlog without switching contexts.

tickgit scans source code for TODO markers (and HACK, FIXME, XXX, etc.) and presents those code comments as tickets, with a fuller context derived from Git history (who added it, when, where etc.).

I am a solo developer building tickgit and tickgit.com to help software engineers be more productive in their code. I hope you find this project interesting and useful!

---

This article is part of The Roadmap, where we look at the creation and promotion of products from the developer’s perspective. We’ll share top lessons from product leaders, and give technical founders a space to share their early-stage products with you. If you’re interested in being featured, let us know.

---

Why?

Project management is an essential part of software development, even for solo developers building a side-project. Plenty of existing ticketing and task management systems help teams and individuals track pending work really thoroughly. Sometimes, though, using TODO comments and other markers within a codebase ends up being a more efficient way of keeping tabs on what needs to get done.

Why // TODO Comments?

TODO comments (or FIXME, HACK, OPTIMIZE, XXX, etc.) are a common way developers indicate that an area of code is worth addressing and returning to. The Linux codebase has 4k+ of these types of comments, Kubernetes has 2k+.

If this sort of thing is a familiar sight, you’ve no doubt seen or used them before:

    // TODO: Get rid of this condition somehow. Perhaps with a dynamic version
    // of the @gate pragma.

TODOs Are Easy

To-dos are easy to add and remove. You don’t need to leave your editor. They’re plaintext. You can include links to additional information. They’re flexible. You can even use emojis 😀✏️. You’re not constrained by the field requirements of an external ticketing system. You can be as thorough or succinct as you’d like in describing why you’re annotating an area of code.

No Context Switching

To-dos are right next to the code they’re describing, which means you don’t lose the context of the codebase: the surrounding classes, functions, variables, etc. Using an external ticketing system requires you to either switch focus when trying to understand a ticket and the relevant pieces of code, or do a great deal of context-copying to help clarify your task.

To-dos allow you to maintain your flow when writing code, and are often a lower mental burden than switching to and from tickets in an external system. To-dos, of course, can link back to an existing ticket for additional information if necessary.

Trackable with Your Code

Since TODO comments are part of your code, they’re stored in version control. They can undergo code-review in your PRs. They have a history and can be attributed to authors, versions, and commits. This can enable project management aware reports about burndown, team responsibilities, tech debt, development efficiency, etc.

The Command-line Tool

The tickgit command-line tool is an open-source project that scans a Git codebase for TODO comments. It runs a Git blame and outputs results with references to file paths and line numbers.

It can be used to query ad-hoc for open TODO comments, and supports CSV output for consumption by other tools (spreadsheets, text processors, etc.).

Here’s an example output:

The CLI is currently pretty simple, but with plans to improve to enable more use cases, including:

• Customization of phrases to match (don’t match XXX but match @TODO in comments)
• Querying and filtering (show me all to-dos added this week, show me only mine, etc.)
• Aggregation queries count by author, average age by author, etc.
• A CI mode to fail with an error if certain criteria are met (no to-dos in certain branches, max 5 to-dos per author, etc.)
• Extract links and customized parsing of comments (extract an assignee, a due date, etc.)

tickgit.com

The tickgit web application is a SaaS that currently integrates with GitHub. It’s free (no sign-up required) to use for public repositories. You can view open TODO comments, and some summary statistics including charts of counts by author and average age by author.

Each TODO comment is presented as a card, which shows similar information as the CLI. Clicking through will bring you to the file and line of the TODO comment in the GitHub UI.

Private repositories are supported for $3/month (for individuals). All features of the free version (for public repos) are in the paid version for private repos.

Some improvements that are on the way include:

• Subscribe to a repository’s TODO comments as a weekly email summary
• Improved querying and filtering (find my to-dos, to-dos older than a date, etc.)
• Support for more Git hosts (GitLab, BitBucket, sourcehut etc.)
• Better integration with third-party tools like Trello, Jira and Slack

Head over to tickgit.com and take it for a spin on one of your public repos. I hope you’ll be surprised at how much more efficiently you can work through the backlog you didn’t even know you had!

Frequently Asked Questions (FAQs) about Tickgit and TODO Comments