Rule proposal: Expiring TODO comments

[sindresorhus]

For example, // TODO [2018-05-01]: Do this thing would be reported from that date and onwards. The date format should be YYYY-MM-DD (ISO 8601).

Would also be nice to support semver, for example, // TODO [>=2]: Do this thing, which would make it report from version 2 and later.

---

IssueHunt Summary

lubien has been rewarded.

Backers (Total: $100.00)

• issuehunt ($100.00)

Submitted pull Requests

• #302 Add expiring-todo-comments rule (#238)

---

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.

---

IssueHunt has been backed by the following sponsors. Become a sponsor

[futpib]

Should they be warnings before the date/version and errors after, or not reported before and reported as warnings after?

Is it ok for a random contributor to get a TODO he has no idea about reported, just because he happen to contribute at the time of it's expiry?

[MrHen]

I really like the "from version 2" variant of this feature because it can give you a way to start progressively cleaning up TODOs. If this option is enabled, should it always warn for TODOs without a date / version?

[sindresorhus]

Should they be warnings before the date/version and errors after, or not reported before and reported as warnings after?

Silent before and error/warning (depends on what the user sets in their config) after.

Is it ok for a random contributor to get a TODO he has no idea about reported, just because he happen to contribute at the time of it's expiry?

Hmm, good point. We could have an opt-in option to not report in pull requests? Can be detected with https://github.com/watson/ci-info#ciispr

If this option is enabled, should it always warn for TODOs without a date / version?

Yes, it would have to replace the functionality of no-warning-comments as it conflicts.

[sindresorhus]

Anything else we cool could do with TODO comments other than versions and dates?

[MrHen]

Anything else we cool could do with TODO comments other than versions and dates?

I've seen specific tools for making sure each TODO has an issue / bug number which is really helpful for making sure TODOs are actually being tracked. It would require an opinion on how to format it. Perhaps, // TODO: #123 - Thing to do here or // TODO (#123) - Thing to do here.

The two common ways I see bug tickets formatted are #123 and ABC-123. Both seem pretty easy to regex which means it would be easy to right a linter for them. Perhaps with a format: 'jira' config on the rule.

---

In terms of dates, treating the date like a timestamp of when the TODO was added might be more intuitive. If I saw:

// TODO 2018-05-01 - Shouldn't do it like this.

I would probably think, "This TODO was added on 05-01". Six months later when the linter complains that I have a six month old TODO I could either:

• Fix the TODO
• Update the timestamp to "approve" the TODO for another six months
• Increase the expiration date in the lint rule

[zeorin]

The other thing one could optionally require in a TODO is an identifier for the author, like a name, username/handle, initials, or email address. I know using the blame/annotate features of your VCS can usually tell you who wrote a line of code, there are situations where that history is lost:

• File name changes (moves)
• Refactoring (moving pieces of code around)
• Reformatting (e.g. after introducing Prettier to a JS codebase).

In all those cases knowing who originally wrote the comment is helpful.

[zeorin]

There are also some other commonly-used comments like FIXME and XXX that I've seen around. Should probably include those.

[sindresorhus]

The two common ways I see bug tickets formatted are #123 and ABC-123. Both seem pretty easy to regex which means it would be easy to right a linter for them. Perhaps with a format: 'jira' config on the rule.

I could see this being useful for companies. Personally, I prefer just keeping my TODOs only in code. Instead having named formats, we could just accept a regex.

I would probably think, "This TODO was added on 05-01". Six months later when the linter complains that I have a six month old TODO I could either:

That's a different use-case than what I proposed though. This limits the duration of a TODO, while mine is for a fixed date. Both are valid, but they serve different purposes.

What if we made the syntax for my proposal // TODO [from: 2018-05-01]: Do this thing. Would that make it clearer?

[sindresorhus]

The other thing one could optionally require in a TODO is an identifier for the author, like a name, username/handle, initials, or email address.

👍 The common syntax I have seen for this is // TODO(sindresorhus): Lorem ipsum..

[sindresorhus]

There are also some other commonly-used comments like FIXME and XXX that I've seen around. Should probably include those.

👍 FIXME. For additional ones, we could allow specifying a list of keywords.

[alexzherdev]

Continuing the idea about semver, should be doable to require a version of a dependency? E.g.,

// TODO [react@>=16.8]: refactor to hooks

[sindresorhus]

@alexzherdev Good idea! That would indeed be very useful.

[futpib]

Also consider TODOs that pop up when a dependency is removed or added (in case you are migrating between substitute packages like lodash/ramda, preact/react etc.)

Not sure which syntax will be best:

// TODO [-lodash]: A workaround for lodash#12345
// TODO [+react]: After switching to react, we will not need this hack

or

// TODO [npm r lodash]: A workaround for lodash#12345
// TODO [npm i react]: After switching to react, we will not need this hack

[sindresorhus]

[+react] 👍