]> git.lizzy.rs Git - rust.git/commit
Rollup merge of #56348 - matklad:todo-macro, r=withoutboats
authorMazdak Farrokhzad <twingoow@gmail.com>
Tue, 19 Mar 2019 14:16:43 +0000 (15:16 +0100)
committerGitHub <noreply@github.com>
Tue, 19 Mar 2019 14:16:43 +0000 (15:16 +0100)
commitd4dd8604eb76683e1bb613cc35d3ad970f4d372f
tree95a2b55faa646337fd6ad3bb901c0112aa5f3fed
parentef4d1c419525e1510aa650e2bec0d8f7449a2130
parent9d408d972f7cf16162ec3ab35e11c659ccee9566
Rollup merge of #56348 - matklad:todo-macro, r=withoutboats

Add todo!() macro

The primary use-case of `todo!()` macro is to be a much easier to type
alternative to `unimplemented!()` macro.

EDIT: hide unpopular proposal about re-purposing unimplemented

<details>
However, instead of just replacing `unimplemented!()`, it gives it a
more nuanced meaning: a thing which is intentionally left
unimplemented and which should not be called at runtime. Usually,
you'd like to prevent such cases statically, but sometimes you, for
example, have to implement a trait only some methods of which are
applicable. There are examples in the wild of code doing this thing,
and in this case, the current message of `unimplemented`, "not *yet*
implemented" is slightly misleading.

With the addition of TODO, you have three nuanced choices for a
`!`-returning macro (in addition to a good-old panic we all love):

  * todo!()
  * unreachable!()
  * unimplemented!()

Here's a rough guideline what each one means:

- `todo`: use it during development, as a "hole" or placeholder. It
  might be a good idea to add a pre-commit hook which checks that
  `todo` is not accidentally committed.

- `unreachable!()`: use it when your code can statically guarantee
  that some situation can not happen. If you use a library and hit
  `unreachable!()` in the library's code, it's definitely a bug in the
  library. It's OK to have `unreachable!()` in the code base,
  although, if possible, it's better to replace it with
  compiler-verified exhaustive checks.

- `unimplemented!()`: use it when the type checker forces you to
  handle some situation, but there's a contract that a callee must not
  actually call the code. If you use a library and hit
  `unimplemented!()`, it's probably a bug in your code, though
  it *could* be a bug in the library (or library docs) as well. It is
  ok-ish to see an `unimplemented!()` in real code, but it usually
  signifies a clunky, eyebrow-rising API.
</details>