Anatomy of a TODO

Catana can process TODOs written in any form, but for better consistency and fine control, it also introduces a derived TODO syntax.

Catana will process a TODO differently based on how it's written.

Comment

Catana processes TODOs in code comments only. The rest of this document uses examples without code comments for better readability only. Catana will not process TODOs written outside code comment.

const = "TODO do this" // Catana will not process this.

Introduction

At its core, Catana is a trigger/action system and can be summarized: "if true, remind user about its TODO".

A concrete example would be to remind you about a TODO on a specific date and would look something like:

TODO(on: '2022-12-17') Remove this when the beta ends.

Being able to define a trigger directly on a TODO helps with visibility and readability for other members of the project. Without having to switch contexts and look at an issue tracker, a user can quickly identify whether a piece of code can be addressed. This document will reference such TODO as "Catana TODO".


This approach works well when you want to be reminded about a TODO when a condition of your choice is met, but it's quite frequent to add a TODO without a specific timeline in sight.

// TODO Fix this when I have some spare time.

This document will reference such TODO as Catana TODO".

Vanilla TODO

Example

// TODO Fix this when I have some spare time.
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        The title

Event

Catana can't (yet! 😅) determine when "some spare time" is. Therefore, Catana will remind the author about its TODO from time to time (very occasionally, you won't be spammed!).

Assignee

The author of the TODO (also known as the assignee) is the user who introduced it in the codebase (inferred from the git commit authorship).

Catana TODO

Example

TODO(on: date("2023-01-01"), to: "bob") A short description of this TODO.
#    ^^  ^^^^  ^^^^^^^^^^    ^^   ^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#    |   |     |             |    |     An optional title.
#    |   |     |             |    |
#    |   |     |             |    The assignee.
#    |   |     |             |
#    |   |     |             The Catana expected keyword to assign a user.
#    |   |     |
#    |   |     Arguments to the Event.
#    |   The name of the event.
#    The Catana expected keyword to add an event.

As you can see, a Catana TODO is more verbose but also more readable:

  • The assignee is clearly defined and helps with discoverability.
  • A well-defined timeframe when to expect this TODO to be addressed.

Event

Catana offers various events that we'll see in detail in the Event section of this document.

Events are at the core of Catana's mechanism to determine if a TODO is ready to be addressed.

To associate an event with a TODO, the on: keyword should be used:

TODO(on: date("2020-01-01"))

Assignee

“Where everyone is responsible, no one is really”.


Catana enforces every TODO to have a designated assignee. The assignee is the one who will be notified when a TODO becomes ready to be addressed. Having an assignee written in the code also helps towards visibility for your colleagues.

To associate an event with a TODO, the to: keyword should be used:

TODO(to: "Bob")
#         ^^^
#         The assignee should be a GitHub login. Catana will make a query to
#         https://github.com/Bob to make sure the assignee exists.

Title

You can append a short description to your TODO (also named the TODO title). It's a good practice to explain why a TODO was added. Catana will display the TODO title on its dashboard and use it when creating GitHub Issues. Catana also uses the TODO title for detecting TODO updates (see Updating a TODO).

The title is optional but recommended.