Design Philosophy

Design Philosophy Skill

Apply these principles when writing or reviewing code.

When to Use

• Proactively when designing new APIs, modules, or data structures
• When refactoring existing code
• When reviewing code for maintainability

Core Principles

1. Minimize Cognitive Load

Code should be easy to understand without loading too much into working memory.

Guidelines:

• Good Separation of Concerns (SoC) means fewer "things" to keep in mind
• Each module/function should have a single, clear responsibility
• Limit the number of concepts a reader must hold simultaneously
• Clean Imports: Use use statements at the top of files rather than inline absolute paths (e.g. crate::Type) to reduce visual noise and cognitive clutter in function bodies.
• No Magic Numbers/Strings: Extract domain-specific numbers and strings (like ANSI mode integers or escape sequences) into named constants (e.g., in tui/src/core/ansi/constants/). Do not use magic numbers directly in business logic or pattern matches, as this requires readers to memorize their meaning.
• Technical Precision: Use standard, precise terminology (e.g., Parameter vs. Argument) to ensure the reader's mental model matches the implementation exactly. See the Terminology Precision guide.

2. Progressive Disclosure

Reveal complexity only when needed.

Guidelines:

• Public APIs should be minimal and intuitive
• Advanced features should be discoverable but not in-your-face
• Documentation follows inverted pyramid: high-level first, details later
• Module structure should guide users from simple to advanced

3. Make Illegal States Unrepresentable

Use the type system to prevent bugs at compile time.

Guidelines:

• Prefer newtypes over primitives (e.g., Index instead of usize)
• Eliminate Boolean Soup / Boolean Blindness: Avoid raw bool flags, function parameters, or return values that obscure intent (e.g. fn process(flag: bool) or fn is_default() -> bool). Replace boolean soup with self-documenting domain enums (e.g. SyntaxHighlightPipeline::R3BLMarkdown instead of is_file_extension_default() -> bool, or HasSelection::Yes / No). Domain enums make call sites self-documenting and leverage Rust's match for exhaustive compiler checking.
• Avoid Boolean Blindness in Mutator Returns (Option<T> / Option<()>): Mutator methods taking &mut self that delete or replace text cannot return borrowed slices (Option<&str>) or metadata offsets (DocSeg) because the borrow checker forbids returning a &str borrowing from self across a &mut self mutation, and deleted bytes no longer exist in memory. Returning a text payload from a &mut self mutator unavoidably requires an owned heap allocation (Option<String>). Return a payload Option<T> (e.g. Option<LineMetadata> for zero-allocation metrics or Option<String> for text) ONLY when callers genuinely consume it. If no text payload is consumed by callers, do not incur speculative allocations. Return Option<()> (Some(()) for success, None for failure). Option<()> achieves the exact same zero-allocation CPU-register performance as bool while eliminating boolean blindness and supporting ? operator chaining.
• Constructor Conventions (Default over No-Arg new()): If a type requires no arguments for construction, derive or implement Default (#[derive(Default)]) and do NOT create a redundant pub fn new() -> Self method. Use parameterized constructors (with_capacity(...) or new(arg: Type)) only when arguments are required.
• Design enums and structs so invalid combinations cannot be constructed
• Move validation from runtime to compile time where possible
• See check-bounds-safety skill for exemplary patterns

4. Abstractions Must Earn Their Keep

An abstraction should reduce cognitive load, not add to it.

Guidelines:

• If understanding the abstraction requires more effort than the concrete code, don't abstract
• Good abstractions match mental models developers already have
• Three similar lines of code is often better than a premature abstraction
• Abstractions should hide complexity, not just move it