sled/doc/engineering_practices/
mod.rs

1//! Over the years that sled development has been active, some practices have
2//! been collected that have helped to reduce risks throughout the codebase.
3//!
4//! # high-level
5//!
6//! * Start with the correctness requirements, ignore the performance impact
7//!   until the end. You'll usually write something faster by focusing on
8//!   keeping things minimal anyway.
9//! * Throw away what can't be done in a day of coding. when you rewrite it
10//!   tomorrow, it will be simpler.
11//!
12//! # testing
13//!
14//! * Don't do what can't be tested to be correct
15//! * For concurrent code, it must be delayable to induce strange histories when
16//!   running under test
17//! * For IO code, it must have a failpoint so that IO errors can be injected
18//!   during testing, as most bugs in cloud systems happen in the untested
19//!   error-handling code
20//! * Lean heavily into model-based property testing. sled should act like a
21//!   `BTreeMap`, even after crashes
22//!
23//! # when testing and performance collide
24//!
25//! * cold code is buggy code
26//! * if you see a significant optimization that will make correctness-critical
27//!   codepaths harder to hit in tests, the optimization should only be created
28//!   if it's possible to artificially increase the chances of hitting the
29//!   codepath in test. Fox example, sled defaults to having an 8mb write
30//!   buffer, but during tests we often turn it down to 512 bytes so that we can
31//!   really abuse the correctness-critical aspects of its behavior.
32//!
33//! # numbers
34//!
35//! * No silent truncation should ever occur when converting numbers
36//! * No silent wrapping should occur
37//! * Crash or return a `ReportableBug` error in these cases
38//! * `as` is forbidden for anything that could lose information
39//! * Clippy's cast lints help us here, and it has been added to all pull
40//!   requests
41
42//! # package
43//!
44//! * dependencies should be minimized to keep compilation simple
45//!
46//! # coding conventions
47//!
48//! * Self should be avoided. We have a lot of code, and it provides no context
49//!   if people are jumping around a lot. Redundancy here improves orientation.