Skip to content

Add todo!() macro#56348

Merged
bors merged 1 commit intorust-lang:masterfrom
matklad:todo-macro
Mar 19, 2019
Merged

Add todo!() macro#56348
bors merged 1 commit intorust-lang:masterfrom
matklad:todo-macro

Conversation

@matklad
Copy link
Contributor

@matklad matklad commented Nov 29, 2018

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.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.