diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc13aa4c..8bf49a8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 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 Modules are declared at the top of the file, before the imports. Public modules