reduce unreachable-code churn after todo!()

[llogiq]

This was prompted by a rant by /u/matthieum on /r/rust. The idea here is that while writing the code, either rust-analyzer or ourselves may insert todo!() at places we intend to implement later. Unfortunately, that marks all following code as unreachable, which will prompt some lint churn.

So to combat that, I modify the lint to check whether the unreachability stems from a todo!() macro and in this case omit the lint (by setting diverges to Diverges::WarnedAlways instead of Always(..)). Hopefully that makes the unreachable code lint less churn-y during development and improve the developer experience.

I inserted the check after when we already found some unreachable code, so perf shouldn't suffer too badly.

[rustbot]

r? @fee1-dead

rustbot has assigned @fee1-dead.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Kivooeo]

Could you please also add a link to the Zulip discussion? It would help provide context.

Also, could you please add a test to demonstrate that it works?

[llogiq]

If we find that this is too heavy on perf (which it would only be in macro-heavy crates where macros produce a lot of exprs of type !), we could first check that the expression has ExprKind::Call(path, [txt]) where path refers to core::panic::panic.

[iago-lito]

Here is the zulip thread.

[llogiq]

Also, could you please add a test to demonstrate that it works?

I added some code to the respective UI test. E.g. current rustc warns on todo!(); let _ = false.

[llogiq]

r? @estebank

[llogiq]

Open question: Should I add some docs to the todo! macro to describe the behavior?

[iago-lito]

I'd personally be happy to read a line about it in the docs, although I would understand that someone steps forward and explains whether/why it'd be off-topic?

[llogiq]

I'm unsure whether this is too cross-cutting a concern, which is why I'm asking.

OTOH, creating another PR just for one line of docs seems wasteful.

[llogiq]

Perhaps something like:

/// The `unreachable_code` lint will ignore code after a `todo!()`. The code will
/// however still be marked as unreachable, which may
/// have effects on type and lifetime checks.

This implies that todo!() could still be in released code without the compiler giving a warning. Perhaps we should upstream clippy's todo lint next and make it warn by default in release mode?

[WaffleLapkin]

r? me

View changes since this review

[WaffleLapkin]

It's a bit hard to discover, but the right directory for the test is tests/ui/reachable

[llogiq]

I'll move the test under a todo.rs there.

[WaffleLapkin]

Can you also add a test for when another macro expands to todo!?

[llogiq]

Sure! 👍

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[WaffleLapkin]

I think having different lints for debug/release is a bad idea, but mentioning this change in todo's docs is good. Either way, this needs T-lang approval, as this is a lint change. Please write a comment explaining the proposal to the language team and nominate this PR for them.

[llogiq]

T-lang nomination

This PR makes the unreachable_code lint ignore code after the todo!() macro. The reasoning behind this is that todo!() is meant as a temporary shortcut while the code is unfinished, and various tools (e.g. rust-analyzer) will insert it at many places as a stand in for code to add, leading to a plethora of unhelpful lint messages, which some perhaps might even consider a false positive. So by avoiding linting unreachable code after todo!(), the user can concentrate on the things they should.

The downside is that a developer won't get any warning on a todo!(). There's a clippy lint against that, though, which we could upstream.

[llogiq]

@rustbot ready

[WaffleLapkin]

code changes look good me, marking as waiting on T-lang decision

View changes since this review

[joshtriplett]

This seems like a tradeoff, which varies depending on how you want to use todo!() and what your workflow is around it.

On the one hand, I can understand that people might not want to be inundated by a whole pile of warnings about code in progress.

On the other hand, sometimes people (myself included) use those warnings about unused parameters and similar to guide the writing of the code that's in progress. For instance, warnings about unused parameters tell me "the code needs to use that parameter, or you need to delete that parameter". That can lead to a form of incremental, compiler-warning-driven development.

[joshtriplett]

Could folks who have the workflow where they don't want those warnings elaborate somewhat on that workflow, to make it easier to understand?

I'm wondering if it might make sense to have a new macro for code-in-progress that specifically suppresses warnings about it, so that people who want the "don't warn me" workflow can use that macro. Given that we already have unreachable!() and unimplemented!() and todo!() which all have different intent, I can easily imagine us adding another such macro for a different workflow that advertises a different intent.

[kpreid]

Could folks who have the workflow where they don't want those warnings elaborate somewhat on that workflow, to make it easier to understand?

1. Sketch out the functions that will be needed to solve the problem at hand. This might be a impl of an existing trait, or it might be something more freeform like “let’s assume that the API for this module can look like this…”.
2. Put todo!() in the bodies of those functions that aren’t easy to implement immediately, so that they are not blocking compilation.
3. Write the code that uses those functions. This provides evidence that the functions/impl not yet written are worth writing. At this stage, warnings from inside the todo!ed code are noise in the way of seeing whether the usages have any problems themselves.
4. Go back and fill in the todo! gaps so the whole thing actually works.

In particular, it's very common for me to write a function that returns a struct, where one of the fields is harder to compute than the rest (or to experimentally add a field to an existing struct). I’d like to be able to todo!() that field without causing the rest of the function to gain warnings.

I want to do “warning driven development”, as you put it, but the warnings aren’t cooperating with my request for “I want to do this part last” which I spell todo!().

I don’t see it as a big deal to not get warnings for todo!() itself because todo!() is greppable, noticeable in code review, and noticeable by any remotely adequate amount of testing. That said, it would also be a reasonable workflow if there were warnings for todo!s only and not for the dead code surrounding them. The narrower spans and uniform messages of such warnings would make them easier to for me to ignore them when they are irrelevant. They would also help people who are not intending to put them off, because it would point to the place that needs to be filled in rather than multiple places surrounding that place.

P.S. That workflow can be set up by the combination of this PR and #![warn(clippy::todo)].