Enforce actionable and trackable `TODO` comments

[bartekpacia]

In Patrol, I have accumulated many TODO comments, and I'm not happy with their quality. I would like to be able enforce "good TODOs" - TODOs that have a link to a GitHub issue so the team doesn't lose track of them.

Examples

BAD

// TODO: set reasonable duration or create new exception for this case

// TODO(bartekpacia): set reasonable duration or create new exception for this case

// TODO(bartekpacia): set reasonable duration or create new exception for this case. See #2137

The last is wrong because it makes no sense to include username in the TODO since the person responsible for the issue will very likely be the author of the issue.

GOOD

// TODO: set reasonable duration or create new exception for this case. See https://github.com/leancodepl/patrol/issues/2137

or we could go full-minimalism style - just require the issue number:

// TODO: set reasonable duration or create new exception for this case. See #2137

To paraphrase:

• GOAL: Enforce every TODO comment to have See #<github-issue-number at the end
• GOAL: Enforce every TODO comment to not have username (e.g. `// TODO(bartekpacia): ...)
• NON GOAL: Check if the provided issue link/number is valid/exists/is really an issue (and not a PR or a discussion)

Question

I'm not sure how multiline TODOs should be treated. Should it be:

// TODO(bartekpacia): set reasonable duration or create new exception for this case
// See https://github.com/leancodepl/patrol/issues/2137

or:

// TODO(bartekpacia): set reasonable duration or create new exception for this case
// TODO(bartekpacia): See https://github.com/leancodepl/patrol/issues/2137

?

[shilangyu]

So https://dart.dev/tools/linter-rules/flutter_style_todos but without the variant that has no link?

[bartekpacia]

Yes, pretty much. I didn't know that lint exists, thanks.

[FirentisTFW]

Regarding multiline todos - how about prefixing them with a tab? They'd also be treated as a one TODO by VSC which we would not achieve using the options from the description (at least by default, according to my knowledge).

// TODO: set reasonable duration or create new exception for this case
//  See https://github.com/leancodepl/patrol/issues/2137

[bartekpacia]

Thanks @FirentisTFW - this is great. I'm curious whether the flutter_style_todos lint would recognize it in the same way as VSCode.