CONTRIBUTING: error/expect messages
- adds an item that all error messages should be lower case, except for proper nouns and variable names. - adds a section on expect messages, following discussion in #3019 and #3053.
This commit is contained in:
parent
c50796c238
commit
0beefda7ea
|
@ -311,6 +311,7 @@ More specifically an error should
|
||||||
- not have `Error` suffix on enum variants.
|
- not have `Error` suffix on enum variants.
|
||||||
- call `internals::impl_from_infallible!`.
|
- call `internals::impl_from_infallible!`.
|
||||||
- implement `std::error::Error` if they are public (feature gated on "std").
|
- implement `std::error::Error` if they are public (feature gated on "std").
|
||||||
|
- have messages in lower case, except for proper nouns and variable names.
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
/// Documentation for the `Error` type.
|
/// Documentation for the `Error` type.
|
||||||
|
@ -330,6 +331,50 @@ internals::impl_from_infallible!(Error);
|
||||||
All errors that live in an `error` module (eg, `foo/error.rs`) and appear in a public function in
|
All errors that live in an `error` module (eg, `foo/error.rs`) and appear in a public function in
|
||||||
`foo` module should be available from `foo` i.e., should be re-exported from `foo/mod.rs`.
|
`foo` module should be available from `foo` i.e., should be re-exported from `foo/mod.rs`.
|
||||||
|
|
||||||
|
##### `expect` messages
|
||||||
|
|
||||||
|
With respect to `expect` messages, they should follow the
|
||||||
|
[Rust standard library guidelines](https://doc.rust-lang.org/std/option/enum.Option.html#recommended-message-style).
|
||||||
|
More specifically, `expect` messages should be used to to describe the reason
|
||||||
|
you expect the operation to succeed.
|
||||||
|
For example, this `expect` message clearly states why the operation should succeed:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
/// Serializes the public key to bytes.
|
||||||
|
pub fn to_bytes(self) -> Vec<u8> {
|
||||||
|
let mut buf = Vec::new();
|
||||||
|
self.write_into(&mut buf).expect("vecs don't error");
|
||||||
|
buf
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Also note that `expect` messages, as with all error messages, should be lower
|
||||||
|
case, except for proper nouns and variable names.
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>The details on why we chose this style</summary>
|
||||||
|
|
||||||
|
According to the [Rust standard library](https://doc.rust-lang.org/std/error/index.html#common-message-styles),
|
||||||
|
there are two common styles for how to write `expect` messages:
|
||||||
|
|
||||||
|
- using the message to present information to users encountering a panic
|
||||||
|
("expect as error message"); and
|
||||||
|
- using the message to present information to developers debugging the panic
|
||||||
|
("expect as precondition").
|
||||||
|
|
||||||
|
We opted to use the "expect as precondition" since it clearly states why the
|
||||||
|
operation should succeed.
|
||||||
|
This may be better for communicating with developers, since they are the target
|
||||||
|
audience for the error message and `rust-bitcoin`.
|
||||||
|
|
||||||
|
If you want to know more about the decision error messages and expect messages,
|
||||||
|
please check:
|
||||||
|
|
||||||
|
- https://github.com/rust-bitcoin/rust-bitcoin/issues/2913
|
||||||
|
- https://github.com/rust-bitcoin/rust-bitcoin/issues/3053
|
||||||
|
- https://github.com/rust-bitcoin/rust-bitcoin/pull/3019
|
||||||
|
</details>
|
||||||
|
|
||||||
#### Rustdocs
|
#### Rustdocs
|
||||||
|
|
||||||
Be liberal with references to BIPs or other documentation; the aim is that devs can learn about
|
Be liberal with references to BIPs or other documentation; the aim is that devs can learn about
|
||||||
|
|
Loading…
Reference in New Issue