mirror of
https://github.com/trezor/trezor-firmware.git
synced 2024-12-23 23:08:14 +00:00
Merge pull request #834 from trezor/tsusanka/docs-exceptions
Docs: add info about exceptions usage
This commit is contained in:
commit
714eb416d1
@ -8,6 +8,9 @@
|
||||
- [Emulator](core/emulator/index.md)
|
||||
- [Apps](core/src/apps.md)
|
||||
- [Tests](core/tests/index.md)
|
||||
- [Miscellaneous](core/misc/index.md)
|
||||
- [SLIP-39](core/misc/slip0039.md)
|
||||
- [Exceptions usage](core/misc/exceptions.md)
|
||||
- [Legacy](legacy/index.md)
|
||||
- [Python](python/index.md)
|
||||
- [trezorlib](python/trezorlib.md)
|
||||
|
36
docs/core/misc/exceptions.md
Normal file
36
docs/core/misc/exceptions.md
Normal file
@ -0,0 +1,36 @@
|
||||
# Exceptions in Core
|
||||
|
||||
From version 2.3.0 we try to follow few rules about how we use exceptions. All new
|
||||
code MUST follow these.
|
||||
|
||||
## Usage
|
||||
|
||||
You MAY use any exceptions in Core's logic. Exceptions from `wire.errors` SHOULD be
|
||||
the final exceptions that are thrown and SHOULD NOT be caught. Note that `wire.Error`
|
||||
is a type of exception that is intended to be sent out over the wire. It should only
|
||||
be used in contexts where that behavior is appropriate.
|
||||
|
||||
Custom exception type hierarchies SHOULD always be derived directly from Exception.
|
||||
They SHOULD NOT be derived from other built-in exceptions (such as ValueError,
|
||||
TypeError, etc.)
|
||||
|
||||
Deriving a custom exception type signals an intention to catch and handle it
|
||||
somewhere in the code. For this reason, custom exception types SHOULD NOT be derived
|
||||
from wire.Error and subclasses.
|
||||
|
||||
Exception strings, including in internal exceptions, SHOULD only be used in cases
|
||||
where the text is intended to be shown on the host. Exception strings MUST NOT
|
||||
contain any sensitive information. An explanation of an internal exception MAY be
|
||||
placed as a comment on the raise statement, to aid debugging. If an exception is
|
||||
thrown with no arguments, the exception class SHOULD be thrown instead of a new
|
||||
object, i.e., `raise CustomError` instead of `raise CustomError()`.
|
||||
|
||||
## Tl;dr
|
||||
|
||||
- Do not use `wire.errors` for `try-catch` statements, use other exceptions.
|
||||
- Use `wire.errors` solely as a way to communicate errors to the Host, do not include
|
||||
them somewhere deep in the stack.
|
||||
- Do not put sensitive information in exception's message. If you are not sure, do not
|
||||
add any message and provide a comment next to the `raise` statement.
|
||||
- Use `raise CustomError` instead of `raise CustomError()` if you are omitting the
|
||||
exception message.
|
@ -1 +1,6 @@
|
||||
# Miscellaneous
|
||||
|
||||
Topics that do not fit elsewhere:
|
||||
|
||||
- [SLIP-39 in Core](core/misc/slip0039.md)
|
||||
- [Exceptions usage](core/misc/exceptions.md)
|
||||
|
@ -30,3 +30,8 @@ Also please have a look at the docs, either in the `docs` folder or at [docs.tr
|
||||
## Security vulnerability disclosure
|
||||
|
||||
Please report suspected security vulnerabilities in private to [security@satoshilabs.com](mailto:security@satoshilabs.com), also see [the disclosure section on the Trezor.io website](https://trezor.io/security/). Please do NOT create publicly viewable issues for suspected security vulnerabilities.
|
||||
|
||||
## Note on terminology
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
|
||||
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
|
||||
|
Loading…
Reference in New Issue
Block a user