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!

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.)

Continue reading Never Forget a TODO Comment with tickgit, Your Repo’s Project Manager on SitePoint.