Merged
Conversation
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The primary use-case of
todo!()macro is to be a much easier to typealternative 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):Here's a rough guideline what each one means:
todo: use it during development, as a "hole" or placeholder. Itmight be a good idea to add a pre-commit hook which checks that
todois not accidentally committed.unreachable!(): use it when your code can statically guaranteethat some situation can not happen. If you use a library and hit
unreachable!()in the library's code, it's definitely a bug in thelibrary. 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 tohandle 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, thoughit 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 usuallysignifies a clunky, eyebrow-rising API.