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.