[developer_hub] Defensive Programming in Substrate Reference Document

developer-hub/Cargo.toml

@@ -18,6 +18,10 @@ frame = { path = "../substrate/frame", features = ["runtime", "experimental"] }
 pallet-examples = { path = "../substrate/frame/examples" }
 pallet-default-config-example = { path = "../substrate/frame/examples/default-config" }
 
+# Extra example pallets 
+pallet-referenda = { path = "../substrate/frame/referenda" }
+pallet-broker = { path = "../substrate/frame/broker" }
+
 # How we build docs in rust-docs
 simple-mermaid = { git = "https://github.com/kianenigma/simple-mermaid.git", branch = "main" }
 docify = "0.2.6"
@@ -57,6 +61,7 @@ sp-api = { path = "../substrate/primitives/api" }
 sp-core = { path = "../substrate/primitives/core" }
 sp-keyring = { path = "../substrate/primitives/keyring" }
 sp-runtime = { path = "../substrate/primitives/runtime" }
+sp-arithmetic = { path = "../substrate/primitives/arithmetic" }
 
 [dev-dependencies]
 parity-scale-codec = "3.6.5"

developer-hub/src/guides/your_first_pallet/mod.rs

@@ -104,8 +104,8 @@
 //! This macro will call `.into()` under the hood.
 #![doc = docify::embed!("./src/guides/your_first_pallet/mod.rs", transfer_better)]
 //!
-//! Moreover, you will learn in the [Safe Defensive Programming
-//! section](crate::reference_docs::safe_defensive_programming) that it is always recommended to use
+//! Moreover, you will learn in the [Defensive Programming
+//! section](crate::reference_docs::defensive_programming) that it is always recommended to use
 //! safe arithmetic operations in your runtime. By using [`frame::traits::CheckedSub`], we can not
 //! only take a step in that direction, but also improve the error handing and make it slightly more
 //! ergonomic.
@@ -288,7 +288,7 @@
 //! The following topics where used in this guide, but not covered in depth. It is suggested to
 //! study them subsequently:
 //!
-//! - [`crate::reference_docs::safe_defensive_programming`].
+//! - [`crate::reference_docs::defensive_programming`].
 //! - [`crate::reference_docs::frame_origin`].
 //! - [`crate::reference_docs::frame_composite_enums`].
 //! - The pallet we wrote in this guide was using `dev_mode`, learn more in

developer-hub/src/reference_docs/mod.rs

@@ -49,7 +49,7 @@ pub mod frame_origin;
 
 /// Learn about how to write safe and defensive code in your FRAME runtime.
 // TODO: @CrackTheCode016
-pub mod safe_defensive_programming;
+pub mod defensive_programming;
 
 /// Learn about composite enums in FRAME-based runtimes, such as "RuntimeEvent" and "RuntimeCall".
 pub mod frame_composite_enums;

docs/mermaid/integer_operation_decision.mmd

@@ -0,0 +1,7 @@
+flowchart LR
+    CH["Checked"]
+    ST["Saturated"]
+    CH-->NEED["The user needs to know that the operation failed - and why"]
+    CH-->DOUBT["Unsure whether this operation could fail/overflow"]
+    ST-->SILENT["Silently reaching upper/lower bound will not result in any damage"]
+    ST-->REASON["In all reasonable circumstances, the number will not overflow, but safety is still desired"]