Process for todo/future/etc... items in code

[jsync-swirlds]

Abstract

Often, it is necessary to note in the formal design documents for software (a.k.a. "code") that a task is incomplete, needs further discussion, or is deferred to a later iteration. There are a great many ways to indicate these things, but most involve some form of tagged comment (the most common tag being TODO). These tagged comments are often forgotten, and may linger in the documents far beyond usefulness. Some processes even forbid such "to do" comments as a result. Here we offer an alternative that may provide a better balance between useful reference and clean design documents.

Process

In our process, tagged comments are written in a Java "Annotation" style, and must refer to an issue opened in Github for the item described. This offers a short and descriptive text within the design document, but also offers a place for much more detailed description of the intended or expected future modification, as well as the tools to track that change to completion (including removing any items tagged for that issue).

Format

We recommend an "Annotation" style for tagged comments. This style incorporates both tag and a parameter for issue(s) tied to that location, as well as a short description.
We recommend the following five (5) defined tags

• "to do" is @todo(###) description
• "deferred work" is @future(###) description
• "known bug" is @bug(###) description
• "in discussion" is @discussion(###) description (here the reference may be a discussion, rather than an issue)
• "decision needed" is @decide(###) description (may also refer to a discussion)

Examples

A "to do" item

@todo(7356) Replace micro-encabulator with a nano-encabulator element.

A "known bug" item

@bug(81723) HTML2 frame parsing reuses a buffer without synchronization.

A "decision needed" item

@decide(192) Should the forward-distant camera image quantization be 8-bit or 4-by-4?.

[jsync-swirlds]

This originally came up in a PR review comment.
@ata-nas @AlfredoG87 @mattp-swirldslabs @georgi-l95 @Nana-EC

[ata-nas]

+1 from my side. I support this and think it is a very good idea because context is being lost (forgotten most of the times) with time and we will need to come up with it again in the future form whatever comment there is. In this way if we are very descriptive and point to a GH issue, the context will remain in the issue.

[ata-nas]

@jsync-swirlds lets raise this discussion in our next daily and bring awareness to it as well so we can resolve it.

[AlfredoG87]

I agree on this, but maybe todo and future are too similar? a todo is by definition a "deferred work" to the future.
Also you could argue that discussion and decide are overlapping terms that could be meant for the same thing, something is in discussion hence a decision is pending.

So to keep things simple I could suggest to keep only:
"to do" is @todo(###) description
"known bug" is @bug(###) description
"in discussion" is @discussion(###) description (here the reference may be a discussion, rather than an issue)

But I agree that this is a nice suggestion and would like to start using it instead of the infamous TODO 😅

[jsync-swirlds]

It's fine to simplify, if everyone is OK with that.

As to the differences and similarities:

• A todo is generally short term, and what to do is well understood
• A future is longer term and what to do is less well defined.
• A discussion is more "this should be discussed", might or might not have alternatives defined, and might or might not include a decision. A Discussion may become a "Decide" item after sufficient discussion, or might not.
• A decide is immediate and is asking for a specific decision between stated alternatives.
• A bug is, I believe, self explanatory.

All items are, in essence, optional (nothing requires use of any of them), the key element is that every in-code "something to be done" comment follows a consistent pattern and includes a link to an issue or discussion, so we can keep track of them and remove them when appropriate.

[ata-nas]

I do like the more optioned approach. Simpler is not always better. If we have a very clear distinction between a todo, future, discussion and decide (or whatever any other set of definitions really) it helps us weigh the situation. In all cases it is clear, there must be taken some action, but the context is vastly different, e.g. in one definition, we know clearly what must be done and how it must be done and we need to do it soon, while in another definition we know that something must be done, but we have no clear definition as to how it must be done and we need more info or team discussion and could either be extended to the future or must be resolved immediately. I do believe if we establish a good system of managing these (and anything really) and if the system is utilized by the team, this would lead to a more coherent and productive experience.

In both cases, the simpler one and the more extended one, the final goal is to simply tag something that must be done with a GH issue. So the question is do we opt for the simpler option with lower barrier of entry and a bit less complexity, or the more optioned approach which adds some context that might change our approach towards the action at hand. Personally, I am more pro the optioned approach, but I am not opposed to the simpler one either, essentially it achieves the same GH issue tagging goal.