vague-todo

Level: warn · Article: Comments

A TODO without context is noise with a timestamp. It will sit there for three years, mocking every developer who reads it.

What it checks

A TODO, FIXME, XXX or HACK comment with fewer than 6 words after the marker and no reference (a ticket like PERF-112 or #4521, or a URL).

Don’t

#![allow(unused)]
fn main() {
impl Users {
    fn find_by_email(&self, email: &Email) -> Option<&User> {
        // TODO: refactor this
        // FIXME
        self.users.iter().find(|user| user.email == *email)
    }
}
}

Refactor what? Why? When?

Do

#![allow(unused)]
fn main() {
impl Users {
    // TODO: this linear scan works at current scale (~500 users) but will
    // need an index once we hit the enterprise tier. See PERF-112.
    fn find_by_email(&self, email: &Email) -> Option<&User> {
        self.users.iter().find(|user| user.email == *email)
    }
}
}

A known tradeoff and a pointer to the follow-up. That is something the code cannot say.

Options

[thresholds]
vague-todo-min-words = 6

Silence it

Write the sentence. If there is nothing to say, delete the TODO.