software-design-principles

name software-design-principles description Object-oriented design principles including object calisthenics, dependency inversion, fail-fast error handling, feature envy detection, and intention-revealing naming. Triggers on: writing new classes or functions, refactoring, code review, 'clean up', method longer than 10 lines, feature envy, primitive obsession, deep nesting. version 1.0.0 Software Design Principles Professional software design patterns and principles for writing maintainable, well-structured code. Critical Rules 🚨 Fail-fast over silent fallbacks. Never use fallback chains ( value ?? backup ?? 'unknown' ). If data should exist, validate and throw a clear error. 🚨 Strive for maximum type-safety. No any . No as . Type escape hatches defeat TypeScript's purpose. There's always a type-safe solution. 🚨 Make illegal states unrepresentable. Use discriminated unions, not optional fields. If a state combination shouldn't exist, make the type system forbid it. 🚨 Inject dependencies, don't instantiate. No new SomeService() inside methods. Pass dependencies through constructors. 🚨 Intention-revealing names only. Never use data , utils , helpers , handler , processor . Name things for what they do in the domain. 🚨 No code comments. Comments are a failure to express intent in code. If you need a comment to explain what code does, the code isn't clear enough—refactor it. 🚨 Use Zod for runtime validation. In TypeScript, use Zod schemas for parsing external data, API responses, and user input. Type inference from schemas keeps types and validation in sync. When This Applies Writing new code (these are defaults, not just refactoring goals) Refactoring existing code Code reviews and design reviews During TDD REFACTOR phase When analyzing coupling and cohesion Core Philosophy Well-designed, maintainable code is far more important than getting things done quickly. Every design decision should favor: Clarity over cleverness Explicit over implicit Fail-fast over silent fallbacks Loose coupling over tight integration Intention-revealing over generic Code Without Comments Never write comments - write expressive code instead. Object Calisthenics Apply object calisthenics principles: The Nine Rules One level of indentation per method In practice, I will tolerate upto 3 Don't use the ELSE keyword Use early returns instead Wrap all primitives and strings Create value objects Encapsulate validation logic Make domain concepts explicit First class collections Classes with collections should contain nothing else One dot per line Don't abbreviate Use full, descriptive names Keep all entities small Small classes (< 150 lines) Small methods (< 10 lines) Small packages/modules Easier to understand and maintain Avoid getters/setters/properties on entities Tell, don't ask Objects should do work, not expose data When to Apply During refactoring: During code review: Feature Envy Detection Method uses another class's data more than its own? Move it there. // ❌ FEATURE ENVY - obsessed with Order's data class InvoiceGenerator { generate ( order : Order ): Invoice { const total = order. getItems (). map ( i => i. getPrice () * i. getQuantity ()). reduce ( ( a,b ) => a+b, 0 ) return new Invoice (total + total * order. getTaxRate () + order. calculateShipping ()) } } // ✅ Move logic to the class it envies class Order { calculateTotal (): number { /* uses this.items, this.taxRate */ } } class InvoiceGenerator { generate ( order : Order ): Invoice { return new Invoice (order. calculateTotal ()) } } Detection: Count external vs own references. More external? Feature envy. Dependency Inversion Principle Don't instantiate dependencies inside methods. Inject them. // ❌ TIGHT COUPLING class OrderProcessor { process ( order : Order ): void { const validator = new OrderValidator () // Hard to test/change const emailer = new EmailService () // Hidden dependency } } // ✅ LOOSE COUPLING class OrderProcessor { constructor ( private validator : OrderValidator , private emailer : EmailService ) {} process ( order : Order ): void { this . validator . isValid (order) // Injected, mockable this . emailer . send (...) // Explicit dependency } } Scan for: new X() inside methods, static method calls. Extract to constructor. Fail-Fast Error Handling NEVER use fallback chains: value ?? backup ?? default ?? 'unknown' // ❌ Validate and throw clear errors instead: // ❌ SILENT FAILURE - hides problems return content. eventType ?? content. className ?? 'Unknown' // ✅ FAIL FAST - immediate, debuggable if (!content. eventType ) { throw new Error ( `Expected 'eventType', got undefined. Keys: [ ${ Object .keys(content)} ]` ) } return content. eventType Error format: Expected [X]. Got [Y]. Context: [debugging info] Naming Conventions Principle: Use business domain terminology and intention-revealing names. Never use generic programmer jargon. Forbidden Generic Names NEVER use these names: data utils helpers common shared manager handler processor These names are meaningless - they tell you nothing about what the code actually does. Intention-Revealing Names Instead of generic names, use specific domain language: // ❌ GENERIC - meaningless class DataProcessor { processData ( data : any ): any { const utils = new DataUtils () return utils. transform (data) } } // ✓ INTENTION-REVEALING - clear purpose class OrderTotalCalculator { calculateTotal ( order : Order ): Money { return taxCalculator. applyTax (order. subtotal , order. taxRate ) } } Naming Checklist For classes: Does the name reveal what the class is responsible for? Is it a noun (or noun phrase) from the domain? Would a domain expert recognize this term? For methods: Does the name reveal what the method does? Is it a verb (or verb phrase)? Does it describe the business operation? For variables: Does the name reveal what the variable contains? Is it specific to this context? Could someone understand it without reading the code? Refactoring Generic Names When you encounter generic names: Understand the purpose : What is this really doing? Ask domain experts : What would they call this? Extract domain concept : Is there a domain term for this? Rename comprehensively : Update all references Type-Driven Design Principle: Follow Scott Wlaschin's type-driven approach to domain modeling. Express domain concepts using the type system. Make Illegal States Unrepresentable Use types to encode business rules: // ❌ PRIMITIVE OBSESSION - illegal states possible interface Order { status : string // Could be any string shippedDate : Date | null // Could be set when status != 'shipped' } // ✓ TYPE-SAFE - illegal states impossible type UnconfirmedOrder = { type : 'unconfirmed' , items : Item [] } type ConfirmedOrder = { type : 'confirmed' , items : Item [], confirmationNumber : string } type ShippedOrder = { type : 'shipped' , items : Item [], confirmationNumber : string , shippedDate : Date } type Order = UnconfirmedOrder | ConfirmedOrder | ShippedOrder Avoid Type Escape Hatches STRICTLY FORBIDDEN without explicit user approval: any type as type assertions ( as unknown as , as any , as SomeType ) @ts-ignore / @ts-expect-error There is always a better type-safe solution. These make code unsafe and defeat TypeScript's purpose. Use the Type System for Validation // ✓ TYPE-SAFE - validates at compile time type PositiveNumber = number & { __brand : 'positive' } function createPositive ( value : number ): PositiveNumber { if (value <= 0 ) { throw new Error ( `Expected positive number, got ${value} ` ) } return value as PositiveNumber } // Can only be called with validated positive numbers function calculateDiscount ( price : PositiveNumber , rate : number ): Money { // price is guaranteed positive by type system } Prefer Immutability Principle: Default to immutable data. Mutation is a source of bugs—unexpected changes, race conditions, and difficult debugging. The Problem: Mutable State // MUTABLE - hard to reason about function processOrder ( order : Order ): void { order. status = 'processing' // Mutates input! order. items . push (freeGift) // Side effect! } // Caller has no idea their object changed const myOrder = getOrder () processOrder (myOrder) // myOrder is now different - surprise! The Solution: Return New Values // IMMUTABLE - predictable function processOrder ( order : Order ): Order { return { ...order, status : 'processing' , items : [...order. items , freeGift] } } // Caller controls what happens const myOrder = getOrder () const processedOrder = processOrder (myOrder) // myOrder unchanged, processedOrder is new Application Rules Prefer const over let Prefer spread ( ... ) over mutation Prefer map / filter / reduce over forEach with mutation If you must mutate, make it explicit and contained YAGNI - You Aren't Gonna Need It Principle: Don't build features until they're actually needed. Speculative code is waste—it costs time to write, time to maintain, and is often wrong when requirements become clear. The Problem: Speculative Generalization // YAGNI VIOLATION - over-engineered for "future" needs interface PaymentProcessor { process ( payment : Payment ): Result refund ( payment : Payment ): Result partialRefund ( payment : Payment , amount : Money ): Result schedulePayment ( payment : Payment , date : Date ): Result recurringPayment ( payment : Payment , schedule : Schedule ): Result // ... 10 more methods "we might need" } // Only ONE method is actually used today Application Rules Build the simplest thing that works Add capabilities when requirements demand them, not before "But we might need it" is not a requirement When Tempted to Cut Corners STOP if you're about to: Use ?? chains → fail fast with clear error instead Use any or as → fix the types, not the symptoms Use new X() inside a method → inject through constructor Name something data , utils , handler → use domain language Add a getter → ask if the object should do the work instead Skip refactor because "it works" → refactor IS part of the work Write a comment → make the code self-explanatory Mutate a parameter → return a new value Build "for later" → build what you need now