Development Philosophy & Standards

Architecture Principles

Layering & Boundaries

• Domain-driven layers: Domain → Application → Infrastructure → Presentation
• Dependency rule: dependencies point inward (outer layers depend on inner)
• Domain layer has NO external dependencies (no frameworks, no database)
• Use ports & adapters (hexagonal architecture) for external integrations
• Keep business logic framework-agnostic

Separation of Concerns

• Each module/class has ONE reason to change (Single Responsibility)
• Separate "what" (business rules) from "how" (implementation details)
• Use interfaces to define contracts, implementations to fulfill them

SOLID Principles

• SRP: Single Responsibility - one class, one reason to change
• OCP: Open/Closed - open for extension, closed for modification
• LSP: Liskov Substitution - subtypes must be substitutable for base types
• ISP: Interface Segregation - many specific interfaces > one general
• DIP: Dependency Inversion - depend on abstractions, not concretions

Design Patterns (When to Use)

Creational

• Factory Method: When object creation logic is complex or varies
• Abstract Factory: When creating families of related objects
• Builder: When constructing complex objects step-by-step
• Singleton: RARELY - only for truly global state (prefer DI)

Structural

• Adapter: When integrating incompatible interfaces
• Decorator: When adding behavior dynamically without subclassing
• Facade: When simplifying complex subsystem interfaces
• Proxy: For lazy loading, access control, or remote objects
• Repository: For abstracting data access layer

Behavioral

• Strategy: When algorithms/behaviors should be interchangeable
• Observer: For event-driven communication between objects
• Command: For encapsulating requests as objects (undo/redo)
• Template Method: When algorithm structure is fixed but steps vary
• State: When object behavior changes based on internal state
• Chain of Responsibility: For processing requests through handler chain

Architectural

• MVC/MVVM: Separating UI concerns
• Service Layer: Coordinating application operations
• Unit of Work: Managing transactions across repositories
• CQRS: Separating read/write operations when beneficial

Code Quality Standards

Naming & Clarity

• Names reveal intent: getUsersByActiveStatus() not get()
• Boolean functions: isValid(), hasPermission(), canExecute()
• Avoid mental mapping: use domain terms, not x, temp, data

Function Design

• Small functions: 5-20 lines ideal, rarely >50
• One level of abstraction per function
• Maximum 3 parameters; use objects for more
• No side effects unless function name indicates it
• Command-query separation: do something OR return something, not both

Class Design

• Small classes: <300 lines typical, rarely >500
• High cohesion: members work together toward single purpose
• Low coupling: minimal dependencies between classes
• Composition over inheritance
• Prefer immutability when possible

Error Handling

• Use exceptions for exceptional cases
• Don't return null; use Optional/Maybe or empty collections
• Fail fast: validate early, fail clearly
• Specific exceptions > generic ones

Testing Philosophy

Test-Driven Development

• Red: Write failing test
• Green: Make it pass (simplest way)
• Refactor: Clean up while tests stay green

Test Structure

• Arrange-Act-Assert pattern
• One assertion concept per test
• Test behavior, not implementation
• Mock external dependencies, not internal ones

Test Coverage

• Unit tests: business logic, algorithms, utilities
• Integration tests: component interactions, database access
• E2E tests: critical user workflows
• Avoid testing framework code or trivial getters/setters

Domain-Driven Design Concepts

Strategic Design

• Bounded contexts: explicit boundaries between models
• Ubiquitous language: shared vocabulary between devs and domain experts
• Context mapping: define relationships between bounded contexts

Tactical Design

• Entities: Objects with identity that persists over time
• Value Objects: Immutable objects defined by their attributes
• Aggregates: Cluster of entities/VOs with consistency boundary
• Domain Events: Record of something significant that happened
• Services: Operations that don't belong to entities/VOs
• Repositories: Access to aggregates (collection illusion)

Refactoring Practices

When to Refactor

• Before adding features (make it easy to add)
• When you see duplication (DRY principle)
• When code smells appear (long functions, large classes, etc.)
• During code review feedback

Common Refactorings

• Extract method/function
• Extract class/interface
• Rename for clarity
• Replace magic numbers with named constants
• Replace conditionals with polymorphism
• Introduce parameter object

Code Smells to Avoid

• Long methods (>20-30 lines)
• Large classes (>300 lines)
• Long parameter lists (>3 params)
• Duplicated code
• Dead code
• Primitive obsession
• Feature envy
• Inappropriate intimacy

Agile & XP Practices

Core Practices

• Continuous integration
• Small, frequent releases
• Collective code ownership
• Coding standards (this document)
• Sustainable pace

Development Cycle

1. Pick smallest valuable increment
2. Write test first (if TDD)
3. Implement simplest solution
4. Refactor for quality
5. Integrate immediately
6. Get feedback

Simplicity Rules (in order)

1. Passes all tests
2. Reveals intention (clear names, structure)
3. No duplication (DRY)
4. Fewest elements (minimal code)

Dependency Management

Dependency Injection

• Prefer constructor injection
• Use DI container/framework when beneficial
• Avoid service locator pattern (hidden dependencies)

Inversion of Control

• Framework calls your code, not vice versa
• Define interfaces for extension points
• Plugin architecture where appropriate

Performance Considerations

• Premature optimization is evil - make it work, then measure
• But design for performance - choose right data structures, algorithms
• Profile before optimizing - don't guess bottlenecks
• Cache strategically - at appropriate layer with clear invalidation

Security Principles

• Never trust user input - validate and sanitize
• Principle of least privilege
• Defense in depth - multiple security layers
• Fail securely - errors shouldn't leak sensitive info
• Keep dependencies updated

Anti-Patterns to Avoid

• God objects (classes that do everything)
• Spaghetti code (no clear structure)
• Golden hammer (using same solution for every problem)
• Cargo cult programming (copying without understanding)
• Shotgun surgery (one change requires many edits)
• Leaky abstractions (implementation details bleeding through)

When to Break Rules

Rules are guidelines, not laws. Break them when:

• The alternative is clearly worse
• You understand WHY the rule exists
• You document the deviation and reasoning
• The team agrees it's the right tradeoff

Priorities (in order)

1. Correct - Software must work
2. Maintainable - Others (future you) can understand/change it
3. Flexible - Can adapt to new requirements
4. Efficient - Performs adequately (not prematurely optimized)