Every TODO in the codebase must have a link to an issue report

[EchoEllet]

It's easy to leave many TODOs for later, add even more on top of them, and then never look back. It's also very common—but it doesn’t solve the underlying technical debt.

Sometimes we can't do X until we do Y first, and that might make sense to check a TODO into the source code, but we must file an issue. Often, many TODOs aren't worth creating an issue; then we should solve them rather than merging the PR.

I do use TODOs too often when I'm working on something or when I have to do something else, and that's fine during development or during PR review. However, the PR should not be merged until solved, or at least file an issue.

We should have a CI check that enforces the TODO style:

// TODO(https://url): Description

OR:

// TODO: Description, https://url

This might seem pedantic, but it’s essential for long-term maintainability. Many experienced developers advocate for this practice:

• Flutter team member
• Robert C. Martin