CONTRIBUTING: document the use of the terms safe and unsafe
This commit is contained in:
parent
70c2f89bdf
commit
01df41bf01
|
|
@ -118,6 +118,27 @@ However, there are some instances where they are acceptable:
|
||||||
3. The presence of `Option::None` or `Result::Err` is truly an unexpected scenario
|
3. The presence of `Option::None` or `Result::Err` is truly an unexpected scenario
|
||||||
and you intend the program to panic.
|
and you intend the program to panic.
|
||||||
|
|
||||||
|
#### Use of the terms "safe" and "safety"
|
||||||
|
|
||||||
|
As we are programming in Rust, the terms safe and unsafe are narrowly defined to
|
||||||
|
refer to the safety in the sense that is common to the Rust programming community,
|
||||||
|
i.e. "Safe Rust" and "Unsafe Rust", as mentioned in [The Rustonomicon].
|
||||||
|
|
||||||
|
With this in mind, we only accept the use of "safe" about code if it is related
|
||||||
|
to implementing something within the realm of Unsafe Rust, as well as upholding
|
||||||
|
guarantees demanded by Safe Rust. The comment must describe why the use of
|
||||||
|
Unsafe Rust is in fact safe (i.e. which invariants are considered), and under
|
||||||
|
which conditions.
|
||||||
|
|
||||||
|
We will not accept the use of "safe" to describe conditions under which code
|
||||||
|
will not panic, i.e. why it would be panic-free to use `unreachable!`, `unwrap`,
|
||||||
|
or `expect`. As we differentiate between "panic-free Rust" and Safe Rust.
|
||||||
|
We will, however, still recommend that those uses are documented – generally
|
||||||
|
using a `# Panics` header followed by an explanatory paragraph in a documenting
|
||||||
|
comment.
|
||||||
|
|
||||||
|
[The Rustonomicon]: https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html
|
||||||
|
|
||||||
#### Module imports
|
#### Module imports
|
||||||
|
|
||||||
Modules are declared at the top of the file, before the imports. Public modules
|
Modules are declared at the top of the file, before the imports. Public modules
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue