Guideline: Rust Style

Summary

Checklist Project structure File structure Function structure Principles Writing software is not just an act of writing for the compiler but writing for your reviewer and those who will debug and change the code in the future. It should be viewed as a form of technical writing and apply the same principles, including: Inverted pyramid or Progressive Disclosure: lead with or highlight the most salient details, letting readers decide how much they want to dig into the low-level details Guide the user through the structure: with writing, you guide the user through organization including topical essays, table of contents, sections, paragraphs, sentences, fragments, and words. Unlike writing, code is heavily cross-referenced (i.e. functions) and your reader has a limited memory shared with a lot of other context. The reader will skim the majority of code Strong abstractions obviate the need to digging into details The weaker the abstraction, the closer it needs to be to the use or not even exist When optimizing for CPU caches, we consider temporal and spatial locality. Let's offer our reader the same benefit. Project structure Prefer mod.rs over name.rs (P-MOD) When splitting a file into a directory, prefer mod.rs for the root module. This ensures the module is an atomic unit for reading (e.g. browsing, searching) or operating on (e.g. moving, renaming). For example, when browsing on GitHub, it can be easy to overlook the existence of a name/ when seeing a name.rs. This is also consistent with lib.rs and main.rs. Automation: enable clippy.self_named_module_files = "warn" Example: src/ stuff/ stuff_files.rs stuff.rs lib.rs Use instead: src/ stuff/ stuff_files.rs mod.rs lib.rs Directory-root modules only re-export (P-DIR-MOD) When splitting a file into a directory, the root of the directory (mod.rs, lib.rs) should only contain re-exports. All definitions should live in topically named files with mod.rs acting as a Table of Contents. It can be confusing for a reader to figu...