1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

//! Over the years that sled development has been active, some practices have
//! been collected that have helped to reduce risks throughout the codebase.
//!
//! # high-level
//!
//! * Start with the correctness requirements, ignore the performance impact
//!   until the end. You'll usually write something faster by focusing on
//!   keeping things minimal anyway.
//! * Throw away what can't be done in a day of coding. when you rewrite it
//!   tomorrow, it will be simpler.
//!
//! # testing
//!
//! * Don't do what can't be tested to be correct
//! * For concurrent code, it must be delayable to induce strange histories when
//!   running under test
//! * For IO code, it must have a failpoint so that IO errors can be injected
//!   during testing, as most bugs in cloud systems happen in the untested
//!   error-handling code
//! * Lean heavily into model-based property testing. sled should act like a
//!   `BTreeMap`, even after crashes
//!
//! # when testing and performance collide
//!
//! * cold code is buggy code
//! * if you see a significant optimization that will make correctness-critical
//!   codepaths harder to hit in tests, the optimization should only be created
//!   if it's possible to artificially increase the chances of hitting the
//!   codepath in test. Fox example, sled defaults to having an 8mb write
//!   buffer, but during tests we often turn it down to 512 bytes so that we can
//!   really abuse the correctness-critical aspects of its behavior.
//!
//! # numbers
//!
//! * No silent truncation should ever occur when converting numbers
//! * No silent wrapping should occur
//! * Crash or return a `ReportableBug` error in these cases
//! * `as` is forbidden for anything that could lose information
//! * Clippy's cast lints help us here, and it has been added to all pull
//!   requests

//! # package
//!
//! * dependencies should be minimized to keep compilation simple
//!
//! # coding conventions
//!
//! * Self should be avoided. We have a lot of code, and it provides no context
//!   if people are jumping around a lot. Redundancy here improves orientation.