# Research Citations for Code Quality Detection Rules

This document provides authoritative sources, academic papers, industry standards, and expert references that support the code quality detection rules implemented in Guardian. These rules are not invented but based on established software engineering principles and best practices.

---

## Table of Contents

1. [Hardcode Detection (Magic Numbers & Strings)](#1-hardcode-detection-magic-numbers--strings)
2. [Circular Dependencies](#2-circular-dependencies)
3. [Clean Architecture / Layered Architecture](#3-clean-architecture--layered-architecture)
4. [Framework Leak Detection](#4-framework-leak-detection)
5. [Entity Exposure (DTO Pattern)](#5-entity-exposure-dto-pattern)
6. [Repository Pattern](#6-repository-pattern)
7. [Naming Conventions](#7-naming-conventions)
8. [General Software Quality Standards](#8-general-software-quality-standards)
9. [Code Complexity Metrics](#9-code-complexity-metrics)
10. [Additional Authoritative Sources](#10-additional-authoritative-sources)
11. [Anemic Domain Model Detection](#11-anemic-domain-model-detection)
12. [Aggregate Boundary Validation (DDD Tactical Patterns)](#12-aggregate-boundary-validation-ddd-tactical-patterns)
13. [Secret Detection & Security](#13-secret-detection--security)
14. [Severity-Based Prioritization & Technical Debt](#14-severity-based-prioritization--technical-debt)
15. [Domain Event Usage Validation](#15-domain-event-usage-validation)
16. [Value Object Immutability](#16-value-object-immutability)
17. [Command Query Separation (CQS/CQRS)](#17-command-query-separation-cqscqrs)
18. [Factory Pattern](#18-factory-pattern)
19. [Specification Pattern](#19-specification-pattern)
20. [Bounded Context](#20-bounded-context)
21. [Persistence Ignorance](#21-persistence-ignorance)
22. [Null Object Pattern](#22-null-object-pattern)
23. [Primitive Obsession](#23-primitive-obsession)
24. [Service Locator Anti-pattern](#24-service-locator-anti-pattern)
25. [Double Dispatch and Visitor Pattern](#25-double-dispatch-and-visitor-pattern)
26. [Entity Identity](#26-entity-identity)
27. [Saga Pattern](#27-saga-pattern)
28. [Anti-Corruption Layer](#28-anti-corruption-layer)
29. [Ubiquitous Language](#29-ubiquitous-language)

---

## 1. Hardcode Detection (Magic Numbers & Strings)

### Academic Research

**What do developers consider magic literals? A smalltalk perspective** (2022)
- Published in ScienceDirect
- Conducted qualitative and quantitative studies on magic literals
- Analyzed 26 developers reviewing about 24,000 literals from more than 3,500 methods
- Studies ranged from small (four classes) to large (7,700 classes) systems
- Reference: [ScienceDirect Article](https://www.sciencedirect.com/science/article/abs/pii/S0950584922000908)

### Industry Standards

**MIT Course 6.031: Software Construction - Code Review**
- Magic numbers fail three key measures of code quality:
  - Not safe from bugs (SFB)
  - Not easy to understand (ETU)
  - Not ready for change (RFC)
- Reference: [MIT Reading 4: Code Review](https://web.mit.edu/6.031/www/sp17/classes/04-code-review/)

**SonarQube Static Analysis Rules**
- Rule RSPEC-109: "Magic numbers should not be used"
- Identifies hardcoded values and magic numbers as code smells
- Reference: [SonarSource C Rule RSPEC-109](https://rules.sonarsource.com/c/rspec-109/)

### Historical Context

**Wikipedia: Magic Number (Programming)**
- Anti-pattern that breaks one of the oldest rules of programming
- Dating back to COBOL, FORTRAN, and PL/1 manuals of the 1960s
- Defined as "using a numeric literal in source code that has a special meaning that is less than clear"
- Reference: [Wikipedia - Magic Number](https://en.wikipedia.org/wiki/Magic_number_(programming))

### Best Practices

**DRY Principle Violation**
- Magic numbers violate the DRY (Don't Repeat Yourself) principle
- Encourage duplicated hardcoded values instead of centralized definitions
- Make code brittle and prone to errors
- Reference: [Stack Overflow - What are magic numbers](https://stackoverflow.com/questions/47882/what-are-magic-numbers-and-why-do-some-consider-them-bad)

---

## 2. Circular Dependencies

### Expert Opinion

**Martin Fowler on Breaking Cycles**
- "Putting abstract classes in supertype package is good way of breaking cycles in the dependency structure"
- Suggests using abstraction as a technique to break circular dependencies
- Reference: [TechTarget - Circular Dependencies in Microservices](https://www.techtarget.com/searchapparchitecture/tip/The-vicious-cycle-of-circular-dependencies-in-microservices)

### Impact on Software Quality

**Maintainability Issues**
- Circular dependencies make code difficult to read and maintain over time
- Open the door to error-prone applications that are difficult to test
- Changes to a single module cause a large ripple effect of errors
- Reference: [TechTarget - Circular Dependencies](https://www.techtarget.com/searchapparchitecture/tip/The-vicious-cycle-of-circular-dependencies-in-microservices)

**Component Coupling**
- "You can't change or evolve components independently of each other"
- Services become hardly maintainable and highly coupled
- Components cannot be tested in isolation
- Reference: [DEV Community - Circular Dependencies Between Microservices](https://dev.to/cloudx/circular-dependencies-between-microservices-11hn)

### Solution Patterns

**Shopify Engineering: Repository Pattern**
- "Remove Circular Dependencies by Using Dependency Injection and the Repository Pattern in Ruby"
- Demonstrates practical application of breaking circular dependencies
- Reference: [Shopify Engineering](https://shopify.engineering/repository-pattern-ruby)

---

## 3. Clean Architecture / Layered Architecture

### The Dependency Rule - Robert C. Martin

**Book: Clean Architecture: A Craftsman's Guide to Software Structure and Design** (2017)
- Author: Robert C. Martin (Uncle Bob)
- Publisher: Prentice Hall
- ISBN: 978-0134494166
- Available at: [Amazon](https://www.amazon.com/Clean-Architecture-Craftsmans-Software-Structure/dp/0134494164)

**The Dependency Rule (Core Principle)**
- "Source code dependencies can only point inwards"
- "Nothing in an inner circle can know anything at all about something in an outer circle"
- "The name of something declared in an outer circle must not be mentioned by the code in the inner circle"
- Reference: [The Clean Architecture Blog Post](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

**Layer Organization**
- Dependencies flow towards higher-level policies and domain logic
- Inner layers (domain) should not depend on outer layers (infrastructure)
- Use dynamic polymorphism to create source code dependencies that oppose the flow of control
- Reference: [Clean Architecture Beginner's Guide](https://betterprogramming.pub/the-clean-architecture-beginners-guide-e4b7058c1165)

**O'Reilly Resources**
- Complete book available through O'Reilly Learning Platform
- Reference: [O'Reilly - Clean Architecture](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/)

### SOLID Principles - Robert C. Martin

**Paper: Design Principles and Design Patterns** (2000)
- Author: Robert C. Martin
- Introduced the basic principles of SOLID design
- SOLID acronym coined by Michael Feathers around 2004
- Reference: [Wikipedia - SOLID](https://en.wikipedia.org/wiki/SOLID)

**Dependency Inversion Principle (DIP)**
- High-level modules should not depend on low-level modules; both should depend on abstractions
- Abstractions should not depend on details; details should depend on abstractions
- Enables loosely coupled components and simpler testing
- Reference: [DigitalOcean - SOLID Principles](https://www.digitalocean.com/community/conceptual-articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design)

**Single Responsibility Principle (SRP)**
- "There should never be more than one reason for a class to change"
- Every class should have only one responsibility
- Classes with single responsibility are easier to understand, test, and modify
- Reference: [Real Python - SOLID Principles](https://realpython.com/solid-principles-python/)

---

## 4. Framework Leak Detection

### Hexagonal Architecture (Ports & Adapters)

**Original Paper: The Hexagonal (Ports & Adapters) Architecture** (2005)
- Author: Alistair Cockburn
- Document: HaT Technical Report 2005.02
- Date: 2005-09-04 (v 0.9)
- Intent: "Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases"
- Reference: [Alistair Cockburn - Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture)

### Domain-Driven Design (DDD) and Hexagonal Architecture

**Domain-Driven Hexagon Repository**
- Comprehensive guide combining DDD with hexagonal architecture
- "Application Core shouldn't depend on frameworks or access external resources directly"
- "External calls should be done through ports (interfaces)"
- Reference: [GitHub - Domain-Driven Hexagon](https://github.com/Sairyss/domain-driven-hexagon)

**AWS Prescriptive Guidance**
- "The hexagonal architecture pattern is used to isolate business logic (domain logic) from related infrastructure code"
- Outer layers can depend on inner layers, but inner layers never depend on outer layers
- Reference: [AWS - Hexagonal Architecture Pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/hexagonal-architecture.html)

### Preventing Logic Leakage

**Ports and Adapters Benefits**
- Shields domain logic from leaking out of application's core
- Prevents technical details (like JPA entities) and libraries (like O/R mappers) from leaking into application
- Keeps application agnostic of external actors
- Reference: [Medium - Hexagonal Architecture](https://medium.com/ssense-tech/hexagonal-architecture-there-are-always-two-sides-to-every-story-bc0780ed7d9c)

**Herberto Graca's Explicit Architecture**
- "DDD, Hexagonal, Onion, Clean, CQRS, … How I put it all together"
- Comprehensive guide on preventing architectural leakage
- Reference: [Herberto Graca's Blog](https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/)

---

## 5. Entity Exposure (DTO Pattern)

### Martin Fowler's Pattern Definition

**Book: Patterns of Enterprise Application Architecture** (2002)
- Author: Martin Fowler
- Publisher: Addison-Wesley
- First introduced the Data Transfer Object (DTO) pattern
- Reference: [Martin Fowler - Data Transfer Object](https://martinfowler.com/eaaCatalog/dataTransferObject.html)

**DTO Pattern Purpose**
- "The main reason for using a Data Transfer Object is to batch up what would be multiple remote calls into a single call"
- "DTOs are called Data Transfer Objects because their whole purpose is to shift data in expensive remote calls"
- Part of implementing a coarse-grained interface needed for remote performance
- Reference: [Martin Fowler's EAA Catalog](https://martinfowler.com/eaaCatalog/dataTransferObject.html)

### LocalDTO Anti-Pattern

**Martin Fowler on Local DTOs**
- "In a local context, DTOs are not just unnecessary but actually harmful"
- Harmful because coarse-grained API is more difficult to use
- Requires extra work moving data from domain/data source layer into DTOs
- Reference: [Martin Fowler - LocalDTO](https://martinfowler.com/bliki/LocalDTO.html)

### Security and Encapsulation Benefits

**Baeldung: The DTO Pattern**
- DTOs provide only relevant information to the client
- Hide sensitive data like passwords for security reasons
- Decoupling persistence model from domain model reduces risk of exposing domain model
- Reference: [Baeldung - DTO Pattern](https://www.baeldung.com/java-dto-pattern)

**Wikipedia: Data Transfer Object**
- Carries data between processes
- Reduces the number of method calls
- Industry-standard pattern for API design
- Reference: [Wikipedia - Data Transfer Object](https://en.wikipedia.org/wiki/Data_transfer_object)

---

## 6. Repository Pattern

### Martin Fowler's Pattern Definition

**Book: Patterns of Enterprise Application Architecture** (2002)
- Author: Martin Fowler
- Publisher: Addison-Wesley
- ISBN: 978-0321127426
- Available at: [Internet Archive](https://archive.org/details/PatternsOfEnterpriseApplicationArchitectureByMartinFowler)

**Repository Pattern Definition**
- "Mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects"
- Listed under Data Source Architectural Patterns
- Main goal: separate domain logic from data persistence logic
- Reference: [Martin Fowler - Repository](https://martinfowler.com/eaaCatalog/repository.html)

**Pattern Purpose**
- "Adding this layer helps minimize duplicate query logic"
- Original definition: "all about minimizing duplicate query logic"
- Chapter 13 of online ebook at O'Reilly
- Reference: [Martin Fowler's EAA Catalog](https://martinfowler.com/eaaCatalog/)

### Microsoft Guidance

**Microsoft Learn: Infrastructure Persistence Layer Design**
- "Designing the infrastructure persistence layer" for microservices and DDD
- Official Microsoft documentation on repository pattern usage
- Reference: [Microsoft Learn - Repository Pattern](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design)

### Domain-Driven Design Context

**Eric Evans Reference**
- "You can also find a good write-up of this pattern in Domain Driven Design"
- Repository is a key tactical pattern in DDD
- Reference: [Stack Overflow - Repository Pattern Author](https://softwareengineering.stackexchange.com/questions/132813/whos-the-author-creator-of-the-repository-pattern)

---

## 7. Naming Conventions

### Use Case Naming

**Use Case Naming Convention: Verb + Noun**
- Default naming pattern: "(Actor) Verb Noun" with actor being optional
- Name must be in the form of VERB-OBJECT with verb in imperative mode
- Examples: "Customer Process Order", "Send Notification"
- Reference: [TM Forum - Use Case Naming Conventions](https://tmforum-oda.github.io/oda-ca-docs/canvas/usecase-library/use-case-naming-conventions.html)

**Good Use Case Names**
- Use meaningful verbs, not generic ones like "Process"
- Specific actions like "Validate the Ordered Items"
- Name must be unique
- Reference: [Tyner Blain - How to Write Good Use Case Names](https://tynerblain.com/blog/2007/01/22/how-to-write-good-use-case-names/)

### Industry Style Guides

**Google Java Style Guide**
- Method names are written in lowerCamelCase
- Class names should be in PascalCase
- Class names are typically nouns or noun phrases (e.g., Character, ImmutableList)
- Reference: [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)

**Airbnb JavaScript Style Guide**
- Avoid single letter names; be descriptive with naming
- Use camelCase when naming objects, functions, and instances
- Use PascalCase when exporting constructor/class/singleton
- Filename should be identical to function's name
- Reference: [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)

**Microsoft Naming Conventions**
- Variables, methods, instance fields: camelCase
- Class and interface names: PascalCase (capitalized CamelCase)
- Constants: CONSTANT_CASE (all uppercase with underscores)
- Reference: [GeeksforGeeks - Java Naming Conventions](https://www.geeksforgeeks.org/java/java-naming-conventions/)

### General Naming Patterns

**Wikipedia: Naming Conventions**
- Classes are nouns or noun phrases
- Methods/functions are verbs or verb phrases to identify actions
- Established convention across multiple programming languages
- Reference: [Wikipedia - Naming Convention](https://en.wikipedia.org/wiki/Naming_convention_(programming))

**Devopedia: Naming Conventions**
- Comprehensive coverage of naming conventions across languages
- Historical context and evolution of naming standards
- Reference: [Devopedia - Naming Conventions](https://devopedia.org/naming-conventions)

---

## 8. General Software Quality Standards

### ISO/IEC 25010 Software Quality Model

**ISO/IEC 25010:2011 (Updated 2023)**
- Title: "Systems and software engineering – Systems and software Quality Requirements and Evaluation (SQuaRE) – System and software quality models"
- Defines eight software quality characteristics
- Reference: [ISO 25010 Official Standard](https://www.iso.org/standard/35733.html)

**Eight Quality Characteristics**
1. Functional suitability
2. Performance efficiency
3. Compatibility
4. Usability
5. Reliability
6. Security
7. Maintainability
8. Portability

**Maintainability Sub-characteristics**
- **Modularity**: Components can be changed with minimal impact on other components
- **Reusability**: Assets can be used in more than one system
- **Analysability**: Effectiveness of impact assessment and failure diagnosis
- **Modifiability**: System can be modified without introducing defects
- **Testability**: Test criteria effectiveness and execution
- Reference: [ISO 25000 Portal](https://iso25000.com/index.php/en/iso-25000-standards/iso-25010)

**Practical Application**
- Used throughout software development lifecycle
- Define quality requirements and evaluate products
- Static analysis plays key role in security and maintainability
- Reference: [Perforce - What is ISO 25010](https://www.perforce.com/blog/qac/what-is-iso-25010)

### SQuaRE Framework

**ISO/IEC 25000 Series**
- System and Software Quality Requirements and Evaluation (SQuaRE)
- Contains framework to evaluate software product quality
- Derived from earlier ISO/IEC 9126 standard
- Reference: [Codacy Blog - ISO 25010 Software Quality Model](https://blog.codacy.com/iso-25010-software-quality-model)

---

## 9. Code Complexity Metrics

### Cyclomatic Complexity

**Original Work: Thomas McCabe** (1976)
- Developed by Thomas McCabe in 1976
- Derived from graph theory
- Measures "the amount of decision logic in a source code function"
- Quantifies the number of independent paths through program's source code
- Reference: [Wikipedia - Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity)

**NIST Recommendations**
- NIST235 indicates that a limit of 10 is a good starting point
- Original limit of 10 proposed by McCabe has significant supporting evidence
- Limits as high as 15 have been used successfully
- Reference: [Microsoft Learn - Cyclomatic Complexity](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-cyclomatic-complexity)

**Research Findings**
- Positive correlation between cyclomatic complexity and defects
- Functions with highest complexity tend to contain the most defects
- "The SATC has found the most effective evaluation is a combination of size and (Cyclomatic) complexity"
- Modules with both high complexity and large size have lowest reliability
- Reference: [Wikipedia - Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity)

### Cognitive Complexity - SonarQube

**Cognitive Complexity Definition**
- Measure of how hard it is to understand code's control flow
- Code with high cognitive complexity is hard to read, understand, test, and modify
- Incremented when code breaks normal linear reading flow
- Reference: [SonarSource - Cognitive Complexity](https://www.sonarsource.com/blog/5-clean-code-tips-for-reducing-cognitive-complexity/)

**Recommended Thresholds**
- General rule: aim for scores below 15
- SonarQube default maximum complexity: 15
- Method Cognitive Complexity greater than 20 commonly used as quality gate
- Reference: [Medium - Cognitive Complexity by SonarQube](https://medium.com/@himanshuganglani/clean-code-cognitive-complexity-by-sonarqube-659d49a6837d)

**Calculation Method**
- Counts if/else conditions, nested loops (for, forEach, do/while)
- Includes try/catch blocks and switch statements
- Mixed operators in conditions increase complexity
- Reference: [SonarQube Documentation - Metrics Definition](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)

### Academic Research on Software Maintainability

**Tool-Based Perspective on Software Code Maintainability Metrics** (2020)
- Authors: Ardito et al.
- Published in: Scientific Programming (Wiley Online Library)
- Systematic Literature Review on maintainability metrics
- Reference: [Wiley - Software Code Maintainability Metrics](https://onlinelibrary.wiley.com/doi/10.1155/2020/8840389)

**Code Reviews and Complexity** (2024)
- Paper: "The utility of complexity metrics during code reviews for CSE software projects"
- Published in: ScienceDirect
- Analyzes metrics gathered via GitHub Actions for pull requests
- Techniques to guide code review considering cyclomatic complexity levels
- Reference: [ScienceDirect - Complexity Metrics](https://www.sciencedirect.com/science/article/abs/pii/S0167739X2400270X)

---

## 10. Additional Authoritative Sources

### Code Smells and Refactoring

**Book: Refactoring: Improving the Design of Existing Code** (1999, 2nd Edition 2018)
- Author: Martin Fowler
- Publisher: Addison-Wesley
- ISBN (1st Ed): 978-0201485677
- ISBN (2nd Ed): 978-0134757599
- Term "code smell" first coined by Kent Beck
- Featured in the 1999 Refactoring book
- Reference: [Martin Fowler - Code Smell](https://martinfowler.com/bliki/CodeSmell.html)

**Code Smell Definition**
- "Certain structures in the code that indicate violation of fundamental design principles"
- "Surface indication that usually corresponds to a deeper problem in the system"
- Heuristics to indicate when to refactor
- Reference: [Wikipedia - Code Smell](https://en.wikipedia.org/wiki/Code_smell)

**Duplication as Major Code Smell**
- Duplication is one of the biggest code smells
- Spotting duplicate code and removing it leads to improved design
- Reference: [Coding Horror - Code Smells](https://blog.codinghorror.com/code-smells/)

### Domain-Driven Design

**Book: Domain-Driven Design: Tackling Complexity in the Heart of Software** (2003)
- Author: Eric Evans
- Publisher: Addison-Wesley Professional
- ISBN: 978-0321125217
- Available at: [Amazon](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)

**DDD Reference Document**
- Official Domain-Driven Design Reference by Eric Evans
- PDF: Domain-­Driven Design Reference (2015)
- Reference: [Domain Language - DDD Reference](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

**Key DDD Concepts**
- Entities: Defined by their identity
- Value Objects: Defined by their attributes
- Aggregates: Clusters of entities that behave as single unit
- Repositories: Separate domain logic from persistence
- Reference: [Martin Fowler - Domain Driven Design](https://martinfowler.com/bliki/DomainDrivenDesign.html)

### Code Complete - Steve McConnell

**Book: Code Complete: A Practical Handbook of Software Construction** (1993, 2nd Edition 2004)
- Author: Steve McConnell
- Publisher: Microsoft Press
- ISBN: 978-0735619678
- Won Jolt Award in 1993
- Best-selling, best-reviewed software development book
- Reference: [Amazon - Code Complete](https://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670)

**Key Topics Covered**
- Naming variables to deciding when to write a subroutine
- Architecture, coding standards, testing, integration
- Software craftsmanship nature
- Main activities: detailed design, construction planning, coding, debugging, testing
- Reference: [Wikipedia - Code Complete](https://en.wikipedia.org/wiki/Code_Complete)

### Architecture Testing Tools

**ArchUnit - Java Architecture Testing**
- Free, simple, and extensible library for checking architecture
- Define rules for architecture using plain Java unit tests
- Out-of-the-box functionality for layered architecture and onion architecture
- Enforce naming conventions, class access, prevention of cycles
- Reference: [ArchUnit Official Site](https://www.archunit.org/)

**ArchUnit Examples**
- Layered Architecture Test examples on GitHub
- Define layers and add constraints for each layer
- Reference: [GitHub - ArchUnit Examples](https://github.com/TNG/ArchUnit-Examples/blob/main/example-plain/src/test/java/com/tngtech/archunit/exampletest/LayeredArchitectureTest.java)

**NetArchTest - .NET Alternative**
- Inspired by ArchUnit for Java
- Enforce architecture conventions in .NET codebases
- Can be used with any unit test framework
- Reference: [GitHub - NetArchTest](https://github.com/BenMorris/NetArchTest)

**InfoQ Article on ArchUnit**
- "ArchUnit Verifies Architecture Rules for Java Applications"
- Professional coverage of architecture verification
- Reference: [InfoQ - ArchUnit](https://www.infoq.com/news/2022/10/archunit/)

---

## 11. Anemic Domain Model Detection

### Martin Fowler's Original Blog Post (2003)

**Blog Post: "Anemic Domain Model"** (November 25, 2003)
- Author: Martin Fowler
- Published: November 25, 2003
- Described as an anti-pattern related to domain driven design and application architecture
- Basic symptom: domain objects have hardly any behavior, making them little more than bags of getters and setters
- Reference: [Martin Fowler - Anemic Domain Model](https://martinfowler.com/bliki/AnemicDomainModel.html)

**Key Problems Identified:**
- "The basic symptom of an Anemic Domain Model is that at first blush it looks like the real thing"
- "There are objects, many named after the nouns in the domain space, and these objects are connected with the rich relationships and structure that true domain models have"
- "The catch comes when you look at the behavior, and you realize that there is hardly any behavior on these objects"
- "This is contrary to the basic idea of object-oriented design; which is to combine data and process together"

**Why It's an Anti-pattern:**
- Fowler argues that anemic domain models incur all of the costs of a domain model, without yielding any of the benefits
- The logic that should be in a domain object is domain logic - validations, calculations, business rules
- Separating data from behavior violates core OOP principles
- Reference: [Wikipedia - Anemic Domain Model](https://en.wikipedia.org/wiki/Anemic_domain_model)

### Rich Domain Model vs Transaction Script

**Martin Fowler: Transaction Script Pattern**
- Transaction Script organizes business logic by procedures where each procedure handles a single request
- Good for simple logic with not-null checks and basic calculations
- Reference: [Martin Fowler - Transaction Script](https://martinfowler.com/eaaCatalog/transactionScript.html)

**When to Use Rich Domain Model:**
- If you have complicated and everchanging business rules involving validation, calculations, and derivations
- Object model handles complex domain logic better than procedural scripts
- Reference: [InformIT - Domain Logic Patterns](https://www.informit.com/articles/article.aspx?p=1398617&seqNum=2)

**Comparison:**
- Transaction Script is better for simple logic
- Domain Model is better when things get complicated with complex business rules
- You can refactor from Transaction Script to Domain Model, but it's a harder change
- Reference: [Medium - Transaction Script vs Domain Model](https://medium.com/@vibstudio_7040/transaction-script-active-record-and-domain-model-the-good-the-bad-and-the-ugly-c5b80a733305)

### Domain-Driven Design Context

**Eric Evans: Domain-Driven Design** (2003)
- Entities should have both identity and behavior
- Rich domain models place business logic within domain entities
- Anemic models violate DDD principles by separating data from behavior
- Reference: Already covered in Section 10 - [Domain-Driven Design Book](#domain-driven-design)

**Community Discussion:**
- Some argue anemic models can follow SOLID design principles
- However, consensus among DDD practitioners aligns with Fowler's anti-pattern view
- Reference: [Stack Overflow - Anemic Domain Model Anti-Pattern](https://stackoverflow.com/questions/6293981/concrete-examples-on-why-the-anemic-domain-model-is-considered-an-anti-pattern)

---

## 12. Aggregate Boundary Validation (DDD Tactical Patterns)

### Eric Evans: Domain-Driven Design (2003)

**Original Book Definition:**
- Aggregate: "A cluster of associated objects that we treat as a unit for the purpose of data changes"
- An aggregate defines a consistency boundary around one or more entities
- Exactly one entity in an aggregate is the root
- Reference: [Microsoft Learn - Tactical DDD](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)

**DDD Reference Document** (2015)
- Official Domain-Driven Design Reference by Eric Evans
- Contains comprehensive definitions of Aggregates and boundaries
- Reference: [Domain Language - DDD Reference PDF](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

### Vaughn Vernon: Implementing Domain-Driven Design (2013)

**Chapter 10: Aggregates** (Page 347)
- Author: Vaughn Vernon
- Publisher: Addison-Wesley
- ISBN: 978-0321834577
- Available at: [Amazon - Implementing DDD](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)

**Key Rules from the Chapter:**
- **Rule: Model True Invariants in Consistency Boundaries**
- **Rule: Design Small Aggregates**
- **Rule: Reference Other Aggregates by Identity**
- **Rule: Use Eventual Consistency Outside the Boundary**

**Effective Aggregate Design Series:**
- Three-part essay series by Vaughn Vernon
- Available as downloadable PDFs
- Licensed under Creative Commons Attribution-NoDerivs 3.0
- Reference: [Kalele - Effective Aggregate Design](https://kalele.io/effective-aggregate-design/)

**Appendix A: Aggregates and Event Sourcing:**
- Additional coverage of aggregate patterns
- Practical implementation guidance
- Reference: Available in the book

### Tactical DDD Patterns

**Microsoft Azure Architecture Center:**
- "Using tactical DDD to design microservices"
- Official Microsoft documentation on aggregate boundaries
- Comprehensive guide for microservices architecture
- Reference: [Microsoft Learn - Tactical DDD](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)

**SOCADK Design Practice Repository:**
- Summaries of artifacts, templates, and techniques for tactical DDD
- Practical examples of aggregate boundary enforcement
- Reference: [SOCADK - Tactical DDD](https://socadk.github.io/design-practice-repository/activities/DPR-TacticDDD.html)

### Why Aggregate Boundaries Matter

**Transactional Boundary:**
- What makes it an aggregate is the transactional boundary
- Changes to aggregate must be atomic
- Ensures consistency within the boundary
- Reference: [Medium - Mastering Aggregate Design](https://medium.com/ssense-tech/ddd-beyond-the-basics-mastering-aggregate-design-26591e218c8c)

**Cross-Aggregate References:**
- Aggregates should only reference other aggregates by ID, not direct entity references
- Prevents tight coupling between aggregates
- Maintains clear boundaries
- Reference: [Lev Gorodinski - Two Sides of DDD](http://gorodinski.com/blog/2013/03/11/the-two-sides-of-domain-driven-design/)

---

## 13. Secret Detection & Security

### OWASP Standards

**OWASP Secrets Management Cheat Sheet**
- Official OWASP best practices and guidelines for secrets management
- Comprehensive coverage of hardcoded credentials risks
- Reference: [OWASP - Secrets Management](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)

**OWASP DevSecOps Guideline**
- Section on Secrets Management (v-0.2)
- Integration with CI/CD pipelines
- Reference: [OWASP - DevSecOps Secrets](https://owasp.org/www-project-devsecops-guideline/latest/01a-Secrets-Management)

**OWASP Password Management: Hardcoded Password**
- Vulnerability documentation on hardcoded passwords
- "It is never a good idea to hardcode a password"
- Makes fixing the problem extremely difficult
- Reference: [OWASP - Hardcoded Password Vulnerability](https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password)

### Key Security Principles

**Don't Hardcode Secrets:**
- Secrets should not be hardcoded
- Should not be unencrypted
- Should not be stored in source code
- Reference: [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)

**Centralized Management:**
- Growing need to centralize storage, provisioning, auditing, rotation, and management of secrets
- Control access and prevent secrets from leaking
- Use purpose-built tools for encryption-at-rest
- Reference: [OWASP SAMM - Secret Management](https://owaspsamm.org/model/implementation/secure-deployment/stream-b/)

**Prevention Tools:**
- Use pre-commit hooks to prevent secrets from entering codebase
- Automated scanning in CI/CD pipelines
- Reference: [GitHub OWASP Secrets Management](https://github.com/dominikdesmit/owasp-secrets-management)

### GitHub Secret Scanning

**Official GitHub Documentation:**
- About Secret Scanning: Automated detection of secrets in repositories
- Scans for patterns and heuristics matching known types of secrets
- Reference: [GitHub Docs - Secret Scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning)

**How It Works:**
- Automatically scans repository contents for sensitive data (API keys, passwords, tokens)
- Scans commits, issues, and pull requests continuously
- Real-time alerts to repository administrators
- Reference: [GitHub Docs - Keeping Secrets Secure](https://docs.github.com/en/code-security/secret-scanning)

**AI-Powered Detection:**
- Copilot Secret Scanning uses large language models (LLMs)
- Identifies unstructured secrets (generic passwords) in source code
- Enhances detection beyond pattern matching
- Reference: [GitHub Docs - Copilot Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/copilot-secret-scanning)

**Supported Patterns:**
- 350+ secret patterns detected
- AWS, GitHub, NPM, SSH, GCP, Slack, Basic Auth, JWT tokens
- Reference: [GitHub Docs - Supported Patterns](https://docs.github.com/en/code-security/secret-scanning/introduction/supported-secret-scanning-patterns)

### Mobile Security

**OWASP Mobile Security:**
- "Secrets security is the most important issue for mobile applications"
- Only safe way: keep secrets off the client side entirely
- Move sensitive information to backend
- Reference: [GitGuardian - OWASP Top 10 Mobile](https://blog.gitguardian.com/owasp-top-10-for-mobile-secrets/)

### Third-Party Tools

**GitGuardian:**
- Secrets security and non-human identity governance
- Enterprise-grade secret detection
- Reference: [GitGuardian Official Site](https://www.gitguardian.com/)

**Yelp detect-secrets:**
- Open-source enterprise-friendly secret detection
- Prevent secrets in code
- Reference: [GitHub - Yelp detect-secrets](https://github.com/Yelp/detect-secrets)

---

## 14. Severity-Based Prioritization & Technical Debt

### Academic Research on Technical Debt Prioritization

**Systematic Literature Review** (2020)
- Title: "A systematic literature review on Technical Debt prioritization"
- Analyzed 557 unique papers, included 44 primary studies
- Finding: "Technical Debt prioritization research is preliminary and there is no consensus on what the important factors are and how to measure them"
- Reference: [ScienceDirect - TD Prioritization](https://www.sciencedirect.com/science/article/pii/S016412122030220X)

**IEEE Conference Paper** (2021)
- Title: "Technical Debt Prioritization: Taxonomy, Methods Results, and Practical Characteristics"
- Systematic mapping review of 112 studies, resulting in 51 unique papers
- Classified methods in two-level taxonomy with 10 categories
- Reference: [IEEE Xplore - TD Prioritization](https://ieeexplore.ieee.org/document/9582595/)

**Identifying Severity of Technical Debt** (2023)
- Journal: Software Quality Journal
- Title: "Identifying the severity of technical debt issues based on semantic and structural information"
- Problem: "Existing studies mainly focus on detecting TD through source code or comments but usually ignore the severity degree of TD issues"
- Proposed approach combining semantic and structural information
- Reference: [Springer - TD Severity](https://link.springer.com/article/10.1007/s11219-023-09651-3)

### SonarQube Severity Classification

**Current Severity Levels** (SonarQube 10.2+)
- Severity levels: **info, low, medium, high, and blocker**
- Reference: [SonarQube Docs - Metrics Definition](https://docs.sonarsource.com/sonarqube-server/user-guide/code-metrics/metrics-definition)

**High/Blocker Severity:**
- An issue with significant probability of severe unintended consequences
- Should be fixed immediately
- Includes bugs leading to production crashes
- Security flaws allowing attackers to extract sensitive data or execute malicious code
- Reference: [SonarQube Docs - Metrics](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)

**Medium Severity:**
- Quality flaw that can highly impact developer's productivity
- Uncovered code, duplicated blocks, unused parameters
- Reference: [SonarQube Documentation](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)

**Low Severity:**
- Quality flaw with slight impact on developer productivity
- Lines too long, switch statements with few cases
- Reference: [SonarQube Documentation](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)

**Info Severity:**
- No expected impact on application
- Informational purposes only
- Reference: [SonarQube Documentation](https://docs.sonarsource.com/sonarqube-server/10.8/user-guide/code-metrics/metrics-definition)

### Legacy SonarQube Classification (pre-10.2)

**Five Severity Levels:**
- **BLOCKER**: Bug with high probability to impact behavior in production (memory leak, unclosed JDBC connection)
- **CRITICAL**: Bug with low probability to impact production behavior OR security flaw (empty catch block, SQL injection)
- **MAJOR**: Quality flaw highly impacting developer productivity (uncovered code, duplicated blocks, unused parameters)
- **MINOR**: Quality flaw slightly impacting developer productivity (lines too long, switch statements < 3 cases)
- **INFO**: Informational only
- Reference: [SonarQube Community - Severity Categories](https://community.sonarsource.com/t/sonarqube-severity-categories/115287)

### Research on Impact and Effectiveness

**Empirical Study** (2020)
- Title: "Some SonarQube issues have a significant but small effect on faults and changes"
- Published in: ScienceDirect (Information and Software Technology)
- Large-scale empirical study on SonarQube issue impact
- Reference: [ScienceDirect - SonarQube Issues](https://www.sciencedirect.com/science/article/abs/pii/S0164121220301734)

**Machine Learning for Prioritization** (2024)
- Recent approaches: "Development teams could integrate models into CI/CD pipelines"
- Automatically flag potential TD issues during code reviews
- Prioritize based on severity
- Reference: [arXiv - Technical Debt Management](https://arxiv.org/html/2403.06484v1)

### Multiple-Case Study

**Aligning TD with Business Objectives** (2018)
- Title: "Aligning Technical Debt Prioritization with Business Objectives: A Multiple-Case Study"
- Demonstrates importance of priority-based technical debt management
- Reference: [ResearchGate - TD Business Alignment](https://www.researchgate.net/publication/328903587_Aligning_Technical_Debt_Prioritization_with_Business_Objectives_A_Multiple-Case_Study)

---

## 15. Domain Event Usage Validation

### Eric Evans: Domain-Driven Design (2003)

**Original Definition:**
- Domain Events: "Something happened that domain experts care about"
- Events capture facts about the domain that have already occurred
- Distinct from system events - they model business-relevant occurrences
- Reference: [Martin Fowler - Domain Event](https://martinfowler.com/eaaDev/DomainEvent.html)

**Book: Domain-Driven Design** (2003)
- Author: Eric Evans
- Publisher: Addison-Wesley Professional
- ISBN: 978-0321125217
- Domain Events weren't explicitly in the original book but evolved from DDD community
- Reference: [DDD Community - Domain Events](https://www.domainlanguage.com/)

### Vaughn Vernon: Implementing Domain-Driven Design (2013)

**Chapter 8: Domain Events**
- Author: Vaughn Vernon
- Comprehensive coverage of Domain Events implementation
- "Model information about activity in the domain as a series of discrete events"
- Reference: [Amazon - Implementing DDD](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)

**Key Principles:**
- Events should be immutable
- Named in past tense (OrderPlaced, UserRegistered)
- Contain all data needed by handlers
- Enable loose coupling between aggregates

### Martin Fowler's Event Patterns

**Event Sourcing:**
- "Capture all changes to an application state as a sequence of events"
- Events become the primary source of truth
- Reference: [Martin Fowler - Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html)

**Event-Driven Architecture:**
- Promotes loose coupling between components
- Enables asynchronous processing
- Reference: [Martin Fowler - Event-Driven](https://martinfowler.com/articles/201701-event-driven.html)

### Why Direct Infrastructure Calls Are Bad

**Coupling Issues:**
- Direct calls create tight coupling between domain and infrastructure
- Makes testing difficult (need to mock infrastructure)
- Violates Single Responsibility Principle
- Reference: [Microsoft - Domain Events Design](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/domain-events-design-implementation)

**Benefits of Domain Events:**
- Decouples domain from side effects
- Enables eventual consistency
- Improves testability
- Supports audit logging naturally
- Reference: [Jimmy Bogard - Domain Events](https://lostechies.com/jimmybogard/2010/04/08/strengthening-your-domain-domain-events/)

---

## 16. Value Object Immutability

### Eric Evans: Domain-Driven Design (2003)

**Value Object Definition:**
- "An object that describes some characteristic or attribute but carries no concept of identity"
- "Value Objects should be immutable"
- When you care only about the attributes of an element, classify it as a Value Object
- Reference: [Martin Fowler - Value Object](https://martinfowler.com/bliki/ValueObject.html)

**Immutability Requirement:**
- "Treat the Value Object as immutable"
- "Don't give it any identity and avoid the design complexities necessary to maintain Entities"
- Reference: [DDD Reference - Value Objects](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

### Martin Fowler on Value Objects

**Blog Post: Value Object** (2016)
- "A small simple object, like money or a date range, whose equality isn't based on identity"
- "I consider value objects to be one of the most important building blocks of good domain models"
- Reference: [Martin Fowler - Value Object](https://martinfowler.com/bliki/ValueObject.html)

**Key Properties:**
- Equality based on attribute values, not identity
- Should be immutable (once created, cannot be changed)
- Side-effect free behavior
- Self-validating (validate in constructor)

### Vaughn Vernon: Implementing DDD

**Chapter 6: Value Objects**
- Detailed implementation guidance
- "Measures, quantifies, or describes a thing in the domain"
- "Can be compared with other Value Objects using value equality"
- "Completely replaceable when the measurement changes"
- Reference: [Vaughn Vernon - Implementing DDD](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)

### Why Immutability Matters

**Thread Safety:**
- Immutable objects are inherently thread-safe
- No synchronization needed for concurrent access
- Reference: [Effective Java - Item 17](https://www.amazon.com/Effective-Java-Joshua-Bloch/dp/0134685997)

**Reasoning About Code:**
- Easier to understand code when objects don't change
- No defensive copying needed
- Simplifies caching and optimization
- Reference: [Oracle Java Tutorials - Immutable Objects](https://docs.oracle.com/javase/tutorial/essential/concurrency/immutable.html)

**Functional Programming Influence:**
- Immutability is a core principle of functional programming
- Reduces side effects and makes code more predictable
- Reference: [Wikipedia - Immutable Object](https://en.wikipedia.org/wiki/Immutable_object)

---

## 17. Command Query Separation (CQS/CQRS)

### Bertrand Meyer: Original CQS Principle

**Book: Object-Oriented Software Construction** (1988, 2nd Ed. 1997)
- Author: Bertrand Meyer
- Publisher: Prentice Hall
- ISBN: 978-0136291558
- Introduced Command Query Separation principle
- Reference: [Wikipedia - CQS](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation)

**CQS Principle:**
- "Every method should either be a command that performs an action, or a query that returns data to the caller, but not both"
- Commands: change state, return nothing (void)
- Queries: return data, change nothing (side-effect free)
- Reference: [Martin Fowler - CommandQuerySeparation](https://martinfowler.com/bliki/CommandQuerySeparation.html)

### Greg Young: CQRS Pattern

**CQRS Documents** (2010)
- Author: Greg Young
- Extended CQS to architectural pattern
- "CQRS is simply the creation of two objects where there was previously only one"
- Reference: [Greg Young - CQRS Documents](https://cqrs.files.wordpress.com/2010/11/cqrs_documents.pdf)

**Key Concepts:**
- Separate models for reading and writing
- Write model (commands) optimized for business logic
- Read model (queries) optimized for display/reporting
- Reference: [Microsoft - CQRS Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs)

### Martin Fowler on CQRS

**Blog Post: CQRS** (2011)
- "At its heart is the notion that you can use a different model to update information than the model you use to read information"
- Warns against overuse: "CQRS is a significant mental leap for all concerned"
- Reference: [Martin Fowler - CQRS](https://martinfowler.com/bliki/CQRS.html)

### Benefits and Trade-offs

**Benefits:**
- Independent scaling of read and write workloads
- Optimized data schemas for each side
- Improved security (separate read/write permissions)
- Reference: [AWS - CQRS Pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/modernization-data-persistence/cqrs-pattern.html)

**Trade-offs:**
- Increased complexity
- Eventual consistency challenges
- More code to maintain
- Reference: [Microsoft - CQRS Considerations](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs#issues-and-considerations)

---

## 18. Factory Pattern

### Gang of Four: Design Patterns (1994)

**Book: Design Patterns: Elements of Reusable Object-Oriented Software**
- Authors: Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides (Gang of Four)
- Publisher: Addison-Wesley
- ISBN: 978-0201633610
- Defines Factory Method and Abstract Factory patterns
- Reference: [Wikipedia - Design Patterns](https://en.wikipedia.org/wiki/Design_Patterns)

**Factory Method Pattern:**
- "Define an interface for creating an object, but let subclasses decide which class to instantiate"
- Lets a class defer instantiation to subclasses
- Reference: [Refactoring Guru - Factory Method](https://refactoring.guru/design-patterns/factory-method)

**Abstract Factory Pattern:**
- "Provide an interface for creating families of related or dependent objects without specifying their concrete classes"
- Reference: [Refactoring Guru - Abstract Factory](https://refactoring.guru/design-patterns/abstract-factory)

### Eric Evans: Factory in DDD Context

**Domain-Driven Design** (2003)
- Chapter 6: "The Life Cycle of a Domain Object"
- Factories encapsulate complex object creation
- "Shift the responsibility for creating instances of complex objects and Aggregates to a separate object"
- Reference: [DDD Reference](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

**DDD Factory Guidelines:**
- Factory should create valid objects (invariants satisfied)
- Two types: Factory for new objects, Factory for reconstitution
- Keep creation logic out of the entity itself
- Reference: Already in Section 10 - Domain-Driven Design

### Why Factories Matter in DDD

**Encapsulation of Creation Logic:**
- Complex aggregates need coordinated creation
- Business rules should be enforced at creation time
- Clients shouldn't know construction details
- Reference: [Vaughn Vernon - Implementing DDD, Chapter 11](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)

**Factory vs Constructor:**
- Constructors should be simple (assign values)
- Factories handle complex creation logic
- Factories can return different types
- Reference: [Effective Java - Item 1: Static Factory Methods](https://www.amazon.com/Effective-Java-Joshua-Bloch/dp/0134685997)

---

## 19. Specification Pattern

### Eric Evans & Martin Fowler

**Original Paper: Specifications** (1997)
- Authors: Eric Evans and Martin Fowler
- Introduced the Specification pattern
- "A Specification states a constraint on the state of another object"
- Reference: [Martin Fowler - Specification](https://martinfowler.com/apsupp/spec.pdf)

**Domain-Driven Design** (2003)
- Chapter 9: "Making Implicit Concepts Explicit"
- Specifications make business rules explicit and reusable
- "Create explicit predicate-like Value Objects for specialized purposes"
- Reference: [DDD Reference](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

### Pattern Definition

**Core Concept:**
- Specification is a predicate that determines if an object satisfies some criteria
- Encapsulates business rules that can be reused and combined
- Reference: [Wikipedia - Specification Pattern](https://en.wikipedia.org/wiki/Specification_pattern)

**Three Main Uses:**
1. **Selection**: Finding objects that match criteria
2. **Validation**: Checking if object satisfies rules
3. **Construction**: Describing what needs to be created
- Reference: [Martin Fowler - Specification](https://martinfowler.com/apsupp/spec.pdf)

### Composite Specifications

**Combining Specifications:**
- AND: Both specifications must be satisfied
- OR: Either specification must be satisfied
- NOT: Specification must not be satisfied
- Reference: [Refactoring Guru - Specification Pattern](https://refactoring.guru/design-patterns/specification)

**Benefits:**
- Reusable business rules
- Testable in isolation
- Readable domain language
- Composable for complex rules
- Reference: [Enterprise Craftsmanship - Specification Pattern](https://enterprisecraftsmanship.com/posts/specification-pattern-c-implementation/)

---

## 20. Bounded Context

### Eric Evans: Domain-Driven Design (2003)

**Original Definition:**
- "A Bounded Context delimits the applicability of a particular model"
- "Explicitly define the context within which a model applies"
- Chapter 14: "Maintaining Model Integrity"
- Reference: [Martin Fowler - Bounded Context](https://martinfowler.com/bliki/BoundedContext.html)

**Key Principles:**
- Each Bounded Context has its own Ubiquitous Language
- Same term can mean different things in different contexts
- Models should not be shared across context boundaries
- Reference: [DDD Reference](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

### Vaughn Vernon: Strategic Design

**Implementing Domain-Driven Design** (2013)
- Chapter 2: "Domains, Subdomains, and Bounded Contexts"
- Detailed guidance on identifying and mapping contexts
- Reference: [Vaughn Vernon - Implementing DDD](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)

**Context Mapping Patterns:**
- Shared Kernel
- Customer/Supplier
- Conformist
- Anti-Corruption Layer
- Open Host Service / Published Language
- Reference: [Context Mapping Patterns](https://www.infoq.com/articles/ddd-contextmapping/)

### Why Bounded Contexts Matter

**Avoiding Big Ball of Mud:**
- Without explicit boundaries, models become entangled
- Different teams step on each other's models
- Reference: [Wikipedia - Big Ball of Mud](https://en.wikipedia.org/wiki/Big_ball_of_mud)

**Microservices and Bounded Contexts:**
- "Microservices should be designed around business capabilities, aligned with bounded contexts"
- Each microservice typically represents one bounded context
- Reference: [Microsoft - Microservices and Bounded Contexts](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/domain-analysis)

### Cross-Context Communication

**Integration Patterns:**
- Never share domain models across contexts
- Use integration events or APIs
- Translate between context languages
- Reference: [Microsoft - Tactical DDD](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)

---

## 21. Persistence Ignorance

### Definition and Principles

**Core Concept:**
- Domain objects should have no knowledge of how they are persisted
- Business logic remains pure and testable
- Infrastructure concerns are separated from domain
- Reference: [Microsoft - Persistence Ignorance](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design#the-persistence-ignorance-principle)

**Wikipedia Definition:**
- "Persistence ignorance is the ability of a class to be used without any underlying persistence mechanism"
- Objects don't know if/how they'll be stored
- Reference: [Wikipedia - Persistence Ignorance](https://en.wikipedia.org/wiki/Persistence_ignorance)

### Eric Evans: DDD and Persistence

**Domain-Driven Design** (2003)
- Repositories abstract away persistence details
- Domain model should not reference ORM or database concepts
- Reference: Already covered in Section 6 - Repository Pattern

**Key Quote:**
- "The domain layer should be kept clean of all technical concerns"
- ORM annotations violate this principle
- Reference: [Clean Architecture and DDD](https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/)

### Clean Architecture Alignment

**Robert C. Martin:**
- "The database is a detail"
- Domain entities should not depend on persistence frameworks
- Use Repository interfaces to abstract persistence
- Reference: [Clean Architecture Book](https://www.amazon.com/Clean-Architecture-Craftsmans-Software-Structure/dp/0134494164)

### Practical Implementation

**Two-Model Approach:**
- Domain Model: Pure business objects
- Persistence Model: ORM-annotated entities
- Mappers translate between them
- Reference: [Microsoft - Infrastructure Layer](https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/infrastructure-persistence-layer-design)

**Benefits:**
- Domain model can evolve independently of database schema
- Easier testing (no ORM required)
- Database can be changed without affecting domain
- Reference: [Enterprise Craftsmanship - Persistence Ignorance](https://enterprisecraftsmanship.com/posts/persistence-ignorance/)

---

## 22. Null Object Pattern

### Original Pattern

**Pattern Languages of Program Design 3** (1997)
- Author: Bobby Woolf
- Chapter: "Null Object"
- Publisher: Addison-Wesley
- ISBN: 978-0201310115
- Reference: [Wikipedia - Null Object Pattern](https://en.wikipedia.org/wiki/Null_object_pattern)

**Definition:**
- "A Null Object provides a 'do nothing' behavior, hiding the details from its collaborators"
- Replaces null checks with polymorphism
- Reference: [Refactoring Guru - Null Object](https://refactoring.guru/introduce-null-object)

### Martin Fowler's Coverage

**Refactoring Book** (1999, 2018)
- "Introduce Null Object" refactoring
- "Replace conditional logic that checks for null with a null object"
- Reference: [Refactoring Catalog](https://refactoring.com/catalog/introduceNullObject.html)

**Special Case Pattern:**
- More general pattern that includes Null Object
- "A subclass that provides special behavior for particular cases"
- Reference: [Martin Fowler - Special Case](https://martinfowler.com/eaaCatalog/specialCase.html)

### Benefits

**Eliminates Null Checks:**
- Reduces cyclomatic complexity
- Cleaner, more readable code
- Follows "Tell, Don't Ask" principle
- Reference: [SourceMaking - Null Object](https://sourcemaking.com/design_patterns/null_object)

**Polymorphism Over Conditionals:**
- Null Object responds to same interface as real object
- Default/neutral behavior instead of null checks
- Reference: [C2 Wiki - Null Object](https://wiki.c2.com/?NullObject)

### When to Use

**Good Candidates:**
- Objects frequently checked for null
- Null represents "absence" with sensible default behavior
- Reference: [Baeldung - Null Object Pattern](https://www.baeldung.com/java-null-object-pattern)

**Cautions:**
- Don't use when null has semantic meaning
- Can hide bugs if misapplied
- Reference: [Stack Overflow - Null Object Considerations](https://stackoverflow.com/questions/1274792/is-the-null-object-pattern-a-bad-practice)

---

## 23. Primitive Obsession

### Code Smell Definition

**Martin Fowler: Refactoring** (1999, 2018)
- Primitive Obsession is a code smell
- "Using primitives instead of small objects for simple tasks"
- Reference: [Refactoring Catalog](https://refactoring.com/catalog/)

**Wikipedia Definition:**
- "Using primitive data types to represent domain ideas"
- Example: Using string for email, int for money
- Reference: [Wikipedia - Code Smell](https://en.wikipedia.org/wiki/Code_smell)

### Why It's a Problem

**Lost Type Safety:**
- String can contain anything, Email cannot
- Compiler can't catch domain errors
- Reference: [Refactoring Guru - Primitive Obsession](https://refactoring.guru/smells/primitive-obsession)

**Scattered Validation:**
- Same validation repeated in multiple places
- Violates DRY principle
- Reference: [SourceMaking - Primitive Obsession](https://sourcemaking.com/refactoring/smells/primitive-obsession)

**Missing Behavior:**
- Primitives can't have domain-specific methods
- Logic lives in services instead of objects
- Reference: [Enterprise Craftsmanship - Primitive Obsession](https://enterprisecraftsmanship.com/posts/functional-c-primitive-obsession/)

### Solutions

**Replace with Value Objects:**
- Money instead of decimal
- Email instead of string
- PhoneNumber instead of string
- Reference: Already covered in Section 16 - Value Object Immutability

**Replace Data Value with Object:**
- Refactoring: "Replace Data Value with Object"
- Introduce Parameter Object for related primitives
- Reference: [Refactoring - Replace Data Value with Object](https://refactoring.com/catalog/replaceDataValueWithObject.html)

### Common Primitive Obsession Examples

**Frequently Misused Primitives:**
- string for: email, phone, URL, currency code, country code
- int/decimal for: money, percentage, age, quantity
- DateTime for: date ranges, business dates
- Reference: [DDD - Value Objects](https://martinfowler.com/bliki/ValueObject.html)

---

## 24. Service Locator Anti-pattern

### Martin Fowler's Analysis

**Blog Post: Inversion of Control Containers and the Dependency Injection pattern** (2004)
- Compares Service Locator with Dependency Injection
- "With service locator the application class asks for it explicitly by a message to the locator"
- Reference: [Martin Fowler - Inversion of Control](https://martinfowler.com/articles/injection.html)

**Service Locator Definition:**
- "The basic idea behind a service locator is to have an object that knows how to get hold of all of the services that an application might need"
- Acts as a registry that provides dependencies on demand
- Reference: [Martin Fowler - Service Locator](https://martinfowler.com/articles/injection.html#UsingAServiceLocator)

### Why It's Considered an Anti-pattern

**Mark Seemann: Dependency Injection in .NET** (2011, 2nd Ed. 2019)
- Author: Mark Seemann
- Extensively covers why Service Locator is problematic
- "Service Locator is an anti-pattern"
- Reference: [Mark Seemann - Service Locator is an Anti-Pattern](https://blog.ploeh.dk/2010/02/03/ServiceLocatorisanAnti-Pattern/)

**Hidden Dependencies:**
- Dependencies are not visible in constructor
- Makes code harder to understand and test
- Violates Explicit Dependencies Principle
- Reference: [DevIQ - Explicit Dependencies](https://deviq.com/principles/explicit-dependencies-principle)

**Testing Difficulties:**
- Need to set up global locator for tests
- Tests become coupled to locator setup
- Reference: [Stack Overflow - Service Locator Testing](https://stackoverflow.com/questions/1557781/is-service-locator-an-anti-pattern)

### Dependency Injection Alternative

**Constructor Injection:**
- Dependencies declared in constructor
- Compiler enforces dependency provision
- Clear, testable code
- Reference: Already covered in Section 6 - Repository Pattern

**Benefits over Service Locator:**
- Explicit dependencies
- Easier testing (just pass mocks)
- IDE support for navigation
- Compile-time checking
- Reference: [Martin Fowler - Constructor Injection](https://martinfowler.com/articles/injection.html#ConstructorInjectionWithPicocontainer)

---

## 25. Double Dispatch and Visitor Pattern

### Gang of Four: Visitor Pattern

**Design Patterns** (1994)
- Authors: Gang of Four
- Visitor Pattern chapter
- "Represent an operation to be performed on the elements of an object structure"
- Reference: [Wikipedia - Visitor Pattern](https://en.wikipedia.org/wiki/Visitor_pattern)

**Intent:**
- "Lets you define a new operation without changing the classes of the elements on which it operates"
- Separates algorithms from object structure
- Reference: [Refactoring Guru - Visitor](https://refactoring.guru/design-patterns/visitor)

### Double Dispatch Mechanism

**Definition:**
- "A mechanism that dispatches a function call to different concrete functions depending on the runtime types of two objects involved in the call"
- Visitor pattern uses double dispatch
- Reference: [Wikipedia - Double Dispatch](https://en.wikipedia.org/wiki/Double_dispatch)

**How It Works:**
1. Client calls element.accept(visitor)
2. Element calls visitor.visit(this) - first dispatch
3. Correct visit() overload selected - second dispatch
- Reference: [SourceMaking - Visitor](https://sourcemaking.com/design_patterns/visitor)

### When to Use

**Good Use Cases:**
- Operations on complex object structures
- Many distinct operations needed
- Object structure rarely changes but operations change often
- Reference: [Refactoring Guru - Visitor Use Cases](https://refactoring.guru/design-patterns/visitor)

**Alternative to Type Checking:**
- Replace instanceof/typeof checks with polymorphism
- More maintainable and extensible
- Reference: [Replace Conditional with Polymorphism](https://refactoring.guru/replace-conditional-with-polymorphism)

### Trade-offs

**Advantages:**
- Open/Closed Principle for new operations
- Related operations grouped in one class
- Accumulate state while traversing
- Reference: [GoF Design Patterns](https://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612)

**Disadvantages:**
- Adding new element types requires changing all visitors
- May break encapsulation (visitors need access to element internals)
- Reference: [C2 Wiki - Visitor Pattern](https://wiki.c2.com/?VisitorPattern)

---

## 26. Entity Identity

### Eric Evans: Domain-Driven Design (2003)

**Entity Definition:**
- "An object that is not defined by its attributes, but rather by a thread of continuity and its identity"
- "Some objects are not defined primarily by their attributes. They represent a thread of identity"
- Reference: [Martin Fowler - Evans Classification](https://martinfowler.com/bliki/EvansClassification.html)

**Identity Characteristics:**
- Unique within the system
- Stable over time (doesn't change)
- Survives state changes
- Reference: [DDD Reference](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

### Vaughn Vernon: Identity Implementation

**Implementing Domain-Driven Design** (2013)
- Chapter 5: "Entities"
- Detailed coverage of identity strategies
- "The primary characteristic of an Entity is that it has a unique identity"
- Reference: [Vaughn Vernon - Implementing DDD](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)

**Identity Types:**
- Natural keys (SSN, email)
- Surrogate keys (UUID, auto-increment)
- Domain-generated IDs
- Reference: [Microsoft - Entity Keys](https://learn.microsoft.com/en-us/ef/core/modeling/keys)

### Identity Best Practices

**Immutability of Identity:**
- Identity should never change after creation
- Use readonly/final fields
- Reference: [StackExchange - Mutable Entity ID](https://softwareengineering.stackexchange.com/questions/375765/is-it-bad-practice-to-have-mutable-entity-ids)

**Value Object for Identity:**
- Wrap identity in Value Object (UserId, OrderId)
- Type safety prevents mixing IDs
- Can include validation logic
- Reference: [Enterprise Craftsmanship - Strongly Typed IDs](https://enterprisecraftsmanship.com/posts/strongly-typed-ids/)

**Equality Based on Identity:**
- Entity equality should compare only identity
- Not all attributes
- Reference: [Vaughn Vernon - Entity Equality](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)

---

## 27. Saga Pattern

### Original Research

**Paper: Sagas** (1987)
- Authors: Hector Garcia-Molina and Kenneth Salem
- Published: ACM SIGMOD Conference
- Introduced Sagas for long-lived transactions
- Reference: [ACM Digital Library - Sagas](https://dl.acm.org/doi/10.1145/38713.38742)

**Definition:**
- "A saga is a sequence of local transactions where each transaction updates data within a single service"
- Alternative to distributed transactions
- Reference: [Microsoft - Saga Pattern](https://learn.microsoft.com/en-us/azure/architecture/reference-architectures/saga/saga)

### Chris Richardson: Microservices Patterns

**Book: Microservices Patterns** (2018)
- Author: Chris Richardson
- Publisher: Manning
- ISBN: 978-1617294549
- Chapter 4: "Managing Transactions with Sagas"
- Reference: [Manning - Microservices Patterns](https://www.manning.com/books/microservices-patterns)

**Saga Types:**
1. **Choreography**: Each service publishes events that trigger next steps
2. **Orchestration**: Central coordinator tells services what to do
- Reference: [Microservices.io - Saga](https://microservices.io/patterns/data/saga.html)

### Compensating Transactions

**Core Concept:**
- Each step has a compensating action to undo it
- If step N fails, compensate steps N-1, N-2, ..., 1
- Reference: [AWS - Saga Pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/modernization-data-persistence/saga-pattern.html)

**Compensation Examples:**
- CreateOrder → DeleteOrder
- ReserveInventory → ReleaseInventory
- ChargePayment → RefundPayment
- Reference: [Microsoft - Compensating Transactions](https://learn.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction)

### Trade-offs

**Advantages:**
- Works across service boundaries
- No distributed locks
- Services remain autonomous
- Reference: [Chris Richardson - Saga](https://chrisrichardson.net/post/microservices/patterns/data/2019/07/22/design-sagas.html)

**Challenges:**
- Complexity of compensation logic
- Eventual consistency
- Debugging distributed sagas
- Reference: [Microsoft - Saga Considerations](https://learn.microsoft.com/en-us/azure/architecture/reference-architectures/saga/saga#issues-and-considerations)

---

## 28. Anti-Corruption Layer

### Eric Evans: Domain-Driven Design (2003)

**Original Definition:**
- Chapter 14: "Maintaining Model Integrity"
- "Create an isolating layer to provide clients with functionality in terms of their own domain model"
- Protects your model from external/legacy models
- Reference: [DDD Reference](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

**Purpose:**
- "The translation layer between a new system and an external system"
- Prevents external model concepts from leaking in
- Reference: [Martin Fowler - Anti-Corruption Layer](https://martinfowler.com/bliki/AntiCorruptionLayer.html)

### Microsoft Guidance

**Azure Architecture Center:**
- "Implement a facade or adapter layer between different subsystems that don't share the same semantics"
- Isolate subsystems by placing an anti-corruption layer between them
- Reference: [Microsoft - ACL Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer)

**When to Use:**
- Integrating with legacy systems
- Migrating from monolith to microservices
- Working with third-party APIs
- Reference: [Microsoft - ACL When to Use](https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer#when-to-use-this-pattern)

### Components of ACL

**Facade:**
- Simplified interface to external system
- Hides complexity from domain
- Reference: [Refactoring Guru - Facade](https://refactoring.guru/design-patterns/facade)

**Adapter:**
- Translates between interfaces
- Maps external model to domain model
- Reference: [Refactoring Guru - Adapter](https://refactoring.guru/design-patterns/adapter)

**Translator:**
- Converts data structures
- Maps field names and types
- Handles semantic differences
- Reference: [Evans DDD - Model Translation](https://www.domainlanguage.com/)

### Benefits

**Isolation:**
- Changes to external system don't ripple through domain
- Domain model remains pure
- Reference: [Microsoft - ACL Benefits](https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer)

**Gradual Migration:**
- Replace legacy components incrementally
- Strangler Fig pattern compatibility
- Reference: [Martin Fowler - Strangler Fig](https://martinfowler.com/bliki/StranglerFigApplication.html)

---

## 29. Ubiquitous Language

### Eric Evans: Domain-Driven Design (2003)

**Original Definition:**
- Chapter 2: "Communication and the Use of Language"
- "A language structured around the domain model and used by all team members"
- "The vocabulary of that Ubiquitous Language includes the names of classes and prominent operations"
- Reference: [Martin Fowler - Ubiquitous Language](https://martinfowler.com/bliki/UbiquitousLanguage.html)

**Key Principles:**
- Shared by developers and domain experts
- Used in code, conversations, and documentation
- Changes to language reflect model changes
- Reference: [DDD Reference](https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf)

### Why It Matters

**Communication Benefits:**
- Reduces translation between business and tech
- Catches misunderstandings early
- Domain experts can read code names
- Reference: [InfoQ - Ubiquitous Language](https://www.infoq.com/articles/ddd-ubiquitous-language/)

**Design Benefits:**
- Model reflects real domain concepts
- Code becomes self-documenting
- Easier onboarding for new team members
- Reference: [Vaughn Vernon - Implementing DDD](https://www.amazon.com/Implementing-Domain-Driven-Design-Vaughn-Vernon/dp/0321834577)

### Building Ubiquitous Language

**Glossary:**
- Document key terms and definitions
- Keep updated as understanding evolves
- Reference: [DDD Community - Glossary](https://thedomaindrivendesign.io/glossary/)

**Event Storming:**
- Collaborative workshop technique
- Discover domain events and concepts
- Build shared understanding and language
- Reference: [Alberto Brandolini - Event Storming](https://www.eventstorming.com/)

### Common Pitfalls

**Inconsistent Terminology:**
- Same concept with different names (Customer/Client/User)
- Different concepts with same name
- Reference: [Domain Language - Building UL](https://www.domainlanguage.com/)

**Technical Terms in Domain:**
- "DTO", "Entity", "Repository" are technical
- Domain should use business terms
- Reference: [Evans DDD - Model-Driven Design](https://www.domainlanguage.com/)

---

## Conclusion

The code quality detection rules implemented in Guardian are firmly grounded in:

1. **Academic Research**: Peer-reviewed papers on software maintainability, complexity metrics, code quality, technical debt prioritization, severity classification, and distributed systems (Sagas)
2. **Industry Standards**: ISO/IEC 25010, SonarQube rules, OWASP security guidelines, Google and Airbnb style guides
3. **Authoritative Books**:
   - Gang of Four's "Design Patterns" (1994)
   - Bertrand Meyer's "Object-Oriented Software Construction" (1988, 1997)
   - Robert C. Martin's "Clean Architecture" (2017)
   - Vaughn Vernon's "Implementing Domain-Driven Design" (2013)
   - Chris Richardson's "Microservices Patterns" (2018)
   - Eric Evans' "Domain-Driven Design" (2003)
   - Martin Fowler's "Patterns of Enterprise Application Architecture" (2002)
   - Martin Fowler's "Refactoring" (1999, 2018)
   - Steve McConnell's "Code Complete" (1993, 2004)
   - Joshua Bloch's "Effective Java" (2001, 2018)
   - Mark Seemann's "Dependency Injection in .NET" (2011, 2019)
   - Bobby Woolf's "Null Object" in PLoPD3 (1997)
4. **Expert Guidance**: Martin Fowler, Robert C. Martin (Uncle Bob), Eric Evans, Vaughn Vernon, Alistair Cockburn, Kent Beck, Greg Young, Bertrand Meyer, Mark Seemann, Chris Richardson, Alberto Brandolini
5. **Security Standards**: OWASP Secrets Management, GitHub Secret Scanning, GitGuardian best practices
6. **Open Source Tools**: ArchUnit, SonarQube, ESLint, Secretlint - widely adopted in enterprise environments
7. **DDD Tactical & Strategic Patterns**: Domain Events, Value Objects, Entities, Aggregates, Bounded Contexts, Anti-Corruption Layer, Ubiquitous Language, Specifications, Factories
8. **Architectural Patterns**: CQS/CQRS, Saga, Visitor/Double Dispatch, Null Object, Persistence Ignorance

These rules represent decades of software engineering wisdom, empirical research, security best practices, and battle-tested practices from the world's leading software organizations and thought leaders.

---

## Additional Resources

### Online Catalogs and References

- Martin Fowler's Enterprise Application Architecture Catalog: https://martinfowler.com/eaaCatalog/
- Martin Fowler's Bliki (Blog + Wiki): https://martinfowler.com/bliki/
- Robert C. Martin's Principles Collection: http://principles-wiki.net/collections:robert_c._martin_s_principle_collection
- Domain Language (Eric Evans): https://www.domainlanguage.com/

### GitHub Repositories

- Airbnb JavaScript Style Guide: https://github.com/airbnb/javascript
- Google Style Guides: https://google.github.io/styleguide/
- Domain-Driven Hexagon: https://github.com/Sairyss/domain-driven-hexagon
- ArchUnit Examples: https://github.com/TNG/ArchUnit-Examples

### Educational Institutions

- MIT Course 6.031: Software Construction: https://web.mit.edu/6.031/www/
- Cornell CS Java Style Guide: https://www.cs.cornell.edu/courses/JavaAndDS/JavaStyle.html

---

**Document Version**: 2.0
**Last Updated**: 2025-12-04
**Questions or want to contribute research?**
- 📧 Email: fozilbek.samiyev@gmail.com
- 🐙 GitHub: https://github.com/samiyev/puaros/issues
**Based on research as of**: December 2025