Merge pull request #3928 from llogiq/todo-overreach

Avoid linting `unreachable_code` on `todo!()`

Author: joshtriplett

text/3928-todo-overreach.md

@@ -0,0 +1,88 @@
+- Feature Name: todo overreach
+- Start Date: 2026-01-31
+- RFC PR: [rust-lang/rfcs#3928](https://github.com/rust-lang/rfcs/pull/3928)
+- Rust Issue: [rust-lang/rust#149543](https://github.com/rust-lang/rust/pull/149543)
+
+## Summary
+[summary]: #summary
+
+The `todo!()` macro is meant as a placeholder, often used to make type check pass while still writing the code. However, since it diverges, all code that comes after it is marked as unreachable. The author proposes changing that to reduce the `unreachable_code` churn, while adding a `todo_macro_calls` lint that can be deactivated while the code is still work in progress and activated before pushing to production.
+
+## Motivation
+[motivation]: #motivation
+
+While working on Rust code, many IDEs as well as rust-analyzer will insert `todo!()` as a placeholder in autogenerated code. Programmers even sometimes manually insert `todo!()` to appease the type checker. However, the `todo!()` macro panics, which means that any code that comes afterwards is unreachable. This leads to `unreachable_code` lint message churn, especially because there is no distinction between code that is unreachable because of `todo!()` and code that is unreachable because of other panics, `return`s, `breaks` or calling other diverging functions.
+
+The goal of this RFC is to instate such a distinction so that users can avoid the useless lint messages while keeping the important ones as they work on the code. This lets the user insert `todo!()` without being bothered by `unreachable_code` warnings, and they can ensure there are no `todo!()` macros left once they're done.
+
+## Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+- First, the `unreachable_code` lint is extended to avoid linting on expressions that come from `todo!()` macro calls, if those calls are directly in the current crate's code. This means code expanded from another macro which contains `todo!()` will still lint `unreachable_code` because the `todo!()` is outside the purview of the programmer's crate – we generally don't require the programmer to modify their dependencies to quell a lint warning.
+- Second, for the `todo!()` macro calls appearing in the current crate and not expanded from external code, a warn-by-default `todo_macro_calls` lint is introcuced. This lint can be deactivated while working on the code, and re-activated once finished.
+
+So for example:
+
+```rust
+fn test(x: Option<String>) {
+    let y = match x.as_ref() {
+        Some(s) => todo!(),
+        None => todo!(),
+    };
+    println!("{y}"); // <- this code would no longer be marked unreachable
+}
+
+/* in `other_crate`:
+macro_rules! macro_containing_todo! {
+    { $x:expr } => {
+        println!("{x:?}");
+        todo!();
+    }
+}
+*/
+
+fn test_external(x: Result<String, std::io::Error>) {
+    let y = other_crate::macro_containing_todo!(x);
+    println!("{y}"); // <- this however would still be marked unreachable
+}
+```
+
+## Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+To implement this, in the `rustc_hir_typeck` crate, there is one check for diverging code. There, we insert a check for a local `todo!()` macro call, and when that check returns `true`, we modify the result to "warned already" so that the code is marked as diverging (and e.g. the rest of type checking works as before), but the `unreachable_code` lint will no longer warn. To compensate for that, we emit the newly added `todo_macro_calls` lint for the expression.
+
+A proof of concept implementation is in [#149543](https://github.com/rust-lang/rust/pull/149543).
+
+## Drawbacks
+[drawbacks]: #drawbacks
+
+- From a theoretical standpoint, implementing this RFC disturbs the conceptual purity of `todo!()`, which is now somehow more than just any old diverging expression with a suggestive name
+- There is a reasonably small bit of complexity added to the compiler, which we need to maintain
+- There is one more lint that people will encounter (although it will merely replace `unreachable_code` on all `todo!()` macro expressions, not add any new messages)
+- People might be confused why they get a lint for `todo!()` instead for unreachable code, especially if they had `#[allow(unreachable_code)]` in their code. The author suggests that this is easily countered with documentation
+
+## Rationale and alternatives
+[rationale-and-alternatives]: #rationale-and-alternatives
+
+- We could do nothing. This leaves the users with the problem stated above.
+- We could make `unreachable_code` ignore `todo!()` without adding a `todo_macro_calls` lint. However, people would need to run clippy (or use a search or other such IDE feature) to get rid of their `todo!()` calls. This is deemed suboptimal from a user experience standpoint.
+- We could only add a `todo_macro_calls` lint without omitting the `todo!()` macro from `unreachable_code` warnings. That would allow people to allow the `unreachable_code` lint while fixing up all `todo!()`s and only then fix the other unreachable code. However, again, the user might forget reactivating the `unreachable_code` lint, potentially leaving their code in a subpar state
+- We could make `allow(unreachable_code)` also suppress `todo_macro_calls`. However, this doesn't seem like a logical parent group.
+
+Please note that this is a language proposal only insofar as that a lint (which is technically part of the language) is changed in accordance with a standard library item. It is not possible to do this without compiler support. There may be a way to implement this so that users could write their own `placeholder!()` macros that do not trip up the `unreachable_code` lint, although at this point the author sees no value in that.
+
+## Prior art
+[prior-art]: #prior-art
+
+In clippy, there is a `todo` lint that would be deprecated as soon as `todo_macro_calls` is available on stable. Also in clippy, we have done a lot of work to reduce low-benefit lint warnings churn over the last years, so this is merely an extension of that work to the compiler.
+
+## Unresolved questions
+[unresolved-questions]: #unresolved-questions
+
+none
+
+## Future possibilities
+[future-possibilities]: #future-possibilities
+
+There could be a shortcut to disable the `todo_macro_calls` lint while working on the code, or e.g. in a rust-analyzer configuration. Also we can document how to deactivate the `todo_macro_calls` lint on `Debug` builds, avoiding lint message churn during development while making sure no `todo!()` call makes it into a release build.