Rust Clean Software Design Principles.

1. Repo management practices (branching, layout, docs, CI, etc.) harness 2. Design principles that keep those repos maintainable and evolvable (SOLID, KISS/DRY/YAGNI, modularity, etc.) dev This will be opinionated toward your world (Rust/C++ libs, DSP, game/engine work, embedded-ish constraints), not generic CRUD apps. 1. Repo management: structure and workflow 1.1 Repository boundaries - Prefer one deployable / product per repo, plus shared libs factored into their own repos or packages (e.g., DSP core, engine core, utility crates). This aligns with guidance to keep application code and configuration/IaC separated into distinct repos for clarity and lifecycle control. devops.stackexchange - Keep environment-specific config out of the main app repo when you have real deployment environments (e.g., separate infra/config repo or deployment repo). devops.stackexchange For your use case: a monorepo can make sense for “suite” projects (plugins + shared DSP + test harness), but still enforce clear module boundaries and minimal cross-coupling. 1.2 Directory layout Aim for a layout that makes “what is this?” obvious in 5 seconds. Typical patterns emphasize modular, loosely coupled design with small, coherent components. handbook.eng.kempnerinstitute.harvard Example for a multi-language project: - src/ (primary app/library code) - include/ or inc/ (for C/C++) - crates/ or libs/ (Rust/C++ libs shared across binaries) - tools/ (one-off tools, analyzers, codegen) - tests/ (integration/system tests) - examples/ (minimal usage demos) - ci/ or .github/ (pipelines, scripts) - docs/ (architecture notes, ADRs, diagrams) - infra/ (if you keep some IaC here; otherwise in a separate repo) devops.stackexchange Key point: keep test and example code close to the modules they exercise to support design for testability and reuse. handbook.eng.kempnerinstitute.harvard 1.3 Branching and commits Modern guidance emphasizes: - Trunk-based or short-lived branches: small, frequent merges minimize integration pain and support continuous delivery. harness - Frequent commits with good messages: frequent, small commits with clear messages improve code history, review, and debugging. reddit - Mandatory code review via PRs/MRs, especially for core modules, reinforces shared understanding and design quality. reddit Concrete minimal policy: - main always releasable. Feature branches only live a few days. - PR requires: - At least one review - Green CI - Updated tests + docs where applicable opslevel 1.4 CI/CD and quality gates Best-practice references emphasize test automation and integration of checks into CI as first-class requirements. opslevel Baseline pipeline: - Fast checks on every push: - Format (e.g., rustfmt, clang-format) - Lint (e.g., clippy, clang-tidy) - Unit tests - Heavier checks (integration tests, e2e, coverage) on main and nightly builds. opslevel - Security and dependency checks where relevant (e.g., SCA, fuzz harnesses for parsers). Treat “testability and reproducibility” as design constraints, not afterthoughts. handbook.eng.kempnerinstitute.harvard 2. Core design principles (code-level) Multiple sources agree on a core set of principles: SOLID, DRY, KISS, and YAGNI. thirstysprout 2.1 KISS and YAGNI first - KISS: favor the simplest design that satisfies requirements. Simplicity reduces bugs and future change cost. dev - YAGNI: don’t implement extension points, parameters, or generalizations until you have a concrete need. This avoids speculative complexity. youtube In practice: when tempted to add “future-proofing,” ask, “what real requirement forces this today?” If none, skip it. 2.2 DRY and SRP - DRY (Don’t Repeat Yourself): ensure each piece of knowledge or logic has a single, authoritative home. thirstysprout - Single Responsibility Principle (SRP): each module/class should have one reason to change. This is often called the highest-impact principle. thirstysprout For your context, DRY and SRP often mean: - Extracting shared DSP primitives into a core crate/lib. - Separating UI wiring, audio graph construction, and DSP code so a change in one doesn’t cascade. 2.3 SOLID as a refinement A practical guide stresses SOLID as a set: SRP, OCP, LSP, ISP, DIP. thirstysprout - OCP (Open/Closed): add features via extension rather than modifying core logic. E.g., plugin-based effect chains or strategy objects. thirstysprout - LSP: ensure derived types behave like their base contracts without surprising callers. Critical for polymorphic APIs. thirstysprout - ISP: expose narrow interfaces; clients shouldn’t depend on methods they don’t use. thirstysprout - DIP: depend on abstractions, not concrete implementations; inject dependencies. youtube In C++/Rust, DIP often means: - Traits or pure virtual interfaces for backends (e.g., audio driver, storage, platform), implemented per platform. - Constructor/Factory parameters for dependencies, not global singletons. 3. Architectural principles for repos Design guides emphasize modular, loosel…