Beginner

// Ubiquitous Language: names come from the domain glossary, not technical layers
// => "Order" not "OrderData"; "Money" not "BigDecimal"; "Quantity" not "int"
public record Order(
    OrderId id,           // => Strongly-typed id, not raw String or long
    CustomerId customerId, // => Makes relationship explicit at the type level
    Money total,          // => Money carries currency — BigDecimal does not
    Quantity quantity      // => Business concept, not primitive int
) {}
 
// Anti-pattern: primitive names lose all domain meaning
// => String id1, String id2 — which is order id? which is customer id?
// => double amount — what currency? what unit?
public record AntiPattern(String id1, String id2, double amount, int count) {}
 
// Usage: UL version reads like a business requirement
Order o = new Order(
    new OrderId("ord-1"),      // => Typed; wrong id kind caught at compile time
    new CustomerId("cust-7"),  // => Cannot accidentally pass OrderId here
    new Money("50.00", "USD"), // => Currency embedded in the value
    new Quantity(3)            // => Quantity, not "3 of what?"
);

// Kotlin: same UL principle; data class adds structural equality automatically
// => Names are identical to Java version — UL is language-agnostic
data class Order(                                                     // => class Order
    val id: OrderId,           // => val = immutable after construction
    val customerId: CustomerId, // => Separate type prevents id mix-up
    val total: Money,          // => Money, not Double
    val quantity: Quantity      // => Domain concept elevated to type
)
 
// Factory usage mirrors domain expert speech: "place an order for 3 items"
val order = Order(                                                    // => order initialised
    id = OrderId("ord-1"),           // => Named params improve call-site clarity
    customerId = CustomerId("cust-7"), // => Explicit; no positional confusion
    total = Money("50.00", "USD"),    // => Currency always present
    quantity = Quantity(3)            // => Type enforces positive int constraint
)

// C# record: init-only properties enforce immutability alongside UL naming
// => Primary constructor syntax keeps declaration concise
public record Order(                                                  // => record Order
    OrderId Id,            // => Typed identity; init-only after construction
    CustomerId CustomerId, // => Pascal case follows C# convention; still UL
    Money Total,           // => Money not decimal; carries currency semantics
    Quantity Quantity       // => Business concept, not int
);                                                                    // => expression
 
// Instantiation reads like business language
var order = new Order(                                                // => order initialised
    Id: new OrderId("ord-1"),           // => Named args clarify intent
    CustomerId: new CustomerId("cust-7"), // => Compile-time id safety
    Total: new Money(50.00m, "USD"),     // => Currency locked at creation
    Quantity: new Quantity(3)            // => Quantity validates positive value
);                                                                    // => expression

import java.math.BigDecimal; // => BigDecimal: exact decimal arithmetic; never use double for money
import java.util.Objects;    // => Objects.hash: null-safe hash helper
 
// Value Object: identity-free; two instances with equal fields ARE equal
// => No id field anywhere — Money IS defined by amount + currency
public final class Money {  // => final: cannot be subclassed; value semantics preserved
    private final BigDecimal amount;  // => final: immutable after construction
    private final String currency;    // => final: currency locked at creation
 
    public Money(BigDecimal amount, String currency) {                // => Money method
        // => Validate before storing; invalid Money cannot exist as an object
        if (amount == null || amount.compareTo(BigDecimal.ZERO) < 0)  // => precondition check
            throw new IllegalArgumentException("Amount must be non-negative"); // => fail fast
        // => Currency must be non-blank; "USD", "EUR" etc.
        if (currency == null || currency.isBlank())                   // => precondition check
            throw new IllegalArgumentException("Currency required"); // => empty string rejected
        this.amount = amount;     // => Stored; no setter exists on this class
        this.currency = currency; // => Stored; cannot change after this line
    }
 
    // Operations produce NEW instances — original is unchanged
    public Money add(Money other) { // => returns Money; never void; immutable design
        // => Mismatched currency is a domain error, not a rounding issue
        if (!this.currency.equals(other.currency))                    // => precondition check
            throw new IllegalArgumentException("Currency mismatch: " + currency + " vs " + other.currency); // => throws if guard fails
            // => detect mix-up at the domain boundary; fail before arithmetic proceeds
        return new Money(this.amount.add(other.amount), this.currency); // => returns new Money(this.amount.add(othe
        // => new Money returned; neither this nor other is mutated
    }
 
    public BigDecimal getAmount()  { return amount; }   // => read-only accessor
    public String    getCurrency() { return currency; } // => read-only accessor
 
    @Override public boolean equals(Object o) { // => override required for structural equality
        // => Structural equality: same amount+currency = interchangeable
        if (!(o instanceof Money m)) return false; // => pattern variable m; type-safe cast
        return amount.compareTo(m.amount) == 0 && currency.equals(m.currency); // => returns amount.compareTo(m.amount) == 
        // => compareTo not equals for BigDecimal: "10.00".equals("10") is false; compareTo == 0 is true
    }
    @Override public int hashCode() { // => must match equals; same fields, same hash
        return Objects.hash(amount.stripTrailingZeros(), currency);   // => returns Objects.hash(amount.stripTrail
        // => stripTrailingZeros: "10.00" and "10" hash equally — consistent with compareTo
    }
    @Override public String toString() { return amount + " " + currency; } // => "10.00 USD"
}
 
Money price = new Money(new BigDecimal("10.00"), "USD"); // => price = 10.00 USD
Money tax   = new Money(new BigDecimal("1.00"),  "USD"); // => tax   =  1.00 USD
Money total = price.add(tax);   // => total = 11.00 USD (brand-new object)
// price is still 10.00 USD — immutability guaranteed; no shared-state bug possible

import java.math.BigDecimal                                           // => namespace/package import
 
// data class: structural equality and copy() generated; val fields = immutable
// => No manual equals/hashCode; Kotlin compiler produces correct implementations
data class Money(val amount: BigDecimal, val currency: String) {      // => class Money
    init {                                                            // => expression
        // => init block runs after primary constructor; enforces invariants
        require(amount >= BigDecimal.ZERO) { "Amount must be non-negative: $amount" } // => precondition check
        require(currency.isNotBlank())     { "Currency must not be blank" } // => precondition check
        // => If require fails, IllegalArgumentException thrown automatically
    }
 
    fun add(other: Money): Money {                                    // => add method
        // => Reject mixed-currency; domain rule enforced here, not in callers
        require(currency == other.currency) { "Currency mismatch: $currency vs ${other.currency}" } // => precondition check
        return Money(amount + other.amount, currency) // => new instance; inputs unchanged
    }
}
 
val price = Money(BigDecimal("10.00"), "USD") // => Money(amount=10.00, currency=USD)
val tax   = Money(BigDecimal("1.00"),  "USD") // => Money(amount=1.00,  currency=USD)
val total = price.add(tax)                    // => Money(amount=11.00, currency=USD)
// price is still Money(amount=10.00) — val fields cannot be reassigned

// sealed record: init-only properties, structural ==, with-expressions built in
// => No manual Equals() or GetHashCode(); compiler generates from all properties
public sealed record Money                                            // => record Money
{
    public decimal Amount   { get; init; } // => init-only: set once, then immutable
    public string  Currency { get; init; } // => init-only: currency locked after ctor
 
    public Money(decimal amount, string currency)                     // => Money method
    {
        // => Validate before assigning; invalid Money cannot be constructed
        if (amount < 0)                        throw new ArgumentException("Negative amount"); // => throws if guard fails
        if (string.IsNullOrWhiteSpace(currency)) throw new ArgumentException("Currency required"); // => throws if guard fails
        Amount   = amount;   // => Assigned once; init property blocks future mutation
        Currency = currency; // => Assigned once
    }
 
    public Money Add(Money other)                                     // => Add method
    {
        // => Currency must match; no silent conversion allowed
        if (Currency != other.Currency) throw new InvalidOperationException("Currency mismatch"); // => throws if guard fails
        return this with { Amount = Amount + other.Amount };          // => returns this with { Amount = Amount + 
        // => with-expression produces a new record; this is unchanged
    }
}
 
var price = new Money(10.00m, "USD"); // => { Amount=10.00, Currency="USD" }
var tax   = new Money(1.00m,  "USD"); // => { Amount=1.00,  Currency="USD" }
var total = price.Add(tax);           // => { Amount=11.00, Currency="USD" }
// price still { Amount=10.00 } — init-only; with-expression created a new record

import java.util.Objects;                                             // => namespace/package import
 
// EmailAddress: single-field Value Object; equality must be structural
// => Two EmailAddress("a@b.com") instances must be equal even as different objects
public final class EmailAddress {                                     // => EmailAddress field
    private final String value; // => normalised lowercase; single source of truth
 
    public EmailAddress(String value) {                               // => EmailAddress method
        // => Validate format; reject null and missing '@'
        if (value == null || !value.contains("@"))                    // => precondition check
            throw new IllegalArgumentException("Invalid email: " + value); // => throws if guard fails
        this.value = value.toLowerCase(); // => normalise; equality is case-insensitive
    }
 
    // Structural equality: compare field, not memory address
    @Override public boolean equals(Object o) {                       // => expression
        if (!(o instanceof EmailAddress e)) return false; // => type-safe pattern variable
        return value.equals(e.value);  // => attribute comparison, not reference comparison
    }
    @Override public int hashCode() { return Objects.hash(value); } // => hash must match equals
    @Override public String toString() { return value; } // => "alice@example.com"
}
 
EmailAddress a = new EmailAddress("Alice@Example.com"); // => normalised: alice@example.com
EmailAddress b = new EmailAddress("alice@example.com"); // => normalised: alice@example.com
boolean structural = a.equals(b);    // => true — same attribute values
boolean reference  = (a == b);       // => false — different heap objects
// Without overriding equals(), structural would be false — a common VO bug

// Kotlin data class: equals() compares all val fields automatically
// => No manual override needed; data class IS the correct choice for Value Objects
data class EmailAddress(val value: String) {                          // => class EmailAddress
    init {                                                            // => expression
        // => Validate in init; invalid email cannot be constructed
        require(value.isNotBlank() && value.contains("@")) { "Invalid email: $value" } // => precondition check
    }
}
 
val a = EmailAddress("alice@example.com") // => EmailAddress(value=alice@example.com)
val b = EmailAddress("alice@example.com") // => EmailAddress(value=alice@example.com)
val structural = a == b    // => true  — data class == delegates to field comparison
val reference  = a === b   // => false — different object references in memory
// == is structural; === is referential — data class makes == do the right thing

// C# record: == operator uses structural equality automatically
// => Compiler generates Equals() comparing all init-only properties
public record EmailAddress(string Value)                              // => record EmailAddress
{
    // Primary constructor syntax; Value is init-only
    public EmailAddress(string value) : this(value.ToLowerInvariant()) // => EmailAddress method
    {
        // => Normalise to lowercase before calling the generated init
        if (!value.Contains('@')) throw new ArgumentException("Invalid email"); // => throws if guard fails
        // => Validation after normalisation; Value property now holds lowercase
    }
}
 
var a = new EmailAddress("Alice@Example.com"); // => Value = "alice@example.com"
var b = new EmailAddress("alice@example.com"); // => Value = "alice@example.com"
bool structural = a == b;                // => true  — record == is structural
bool reference  = ReferenceEquals(a, b); // => false — different objects
// C# record provides correct VO equality without a single line of boilerplate

import java.util.regex.Pattern;                                       // => namespace/package import
 
// Smart constructor: validation is mandatory, not optional
// => Caller cannot construct a PostalCode and then forget to validate
public final class PostalCode {                                       // => PostalCode field
    private static final Pattern US = Pattern.compile("^\\d{5}(-\\d{4})?$"); // => US declared
    // => Compiled once at class load; cheap to reuse on every validation
    private final String value; // => final: immutable after validation passes
 
    public PostalCode(String value) {                                 // => PostalCode method
        // => Validate before storing; invalid cannot escape this constructor
        if (value == null || !US.matcher(value).matches())            // => precondition check
            throw new IllegalArgumentException("Invalid US postal code: " + value); // => throws if guard fails
        this.value = value; // => Only reachable if pattern matched
    }
 
    // Static factory: same validation, reads more naturally at call sites
    public static PostalCode of(String v) { return new PostalCode(v); } // => of method
    // => PostalCode.of("10001") vs new PostalCode("10001") — both identical behaviour
 
    public String getValue()          { return value; } // => read-only
    @Override public String toString() { return value; } // => "10001"
}
 
PostalCode valid = PostalCode.of("10001");   // => Succeeds; value = "10001"
// PostalCode bad = PostalCode.of("abc");    // => throws IllegalArgumentException
// After construction, every PostalCode variable is guaranteed valid — no null-checks downstream

// private constructor + companion factory: callers must use of(); cannot bypass validation
class PostalCode private constructor(val value: String) {             // => class PostalCode
    // => private constructor: prevents direct new PostalCode("abc")
    init {                                                            // => expression
        // => init runs after constructor; validates invariant
        require(value.matches(Regex("^\\d{5}(-\\d{4})?\$"))) {        // => precondition check
            "Invalid US postal code: $value" // => message embedded in require
        }
    }
 
    companion object {                                                // => expression
        fun of(value: String): PostalCode = PostalCode(value)         // => of method
        // => Factory delegates to private constructor; same validation path
    }
 
    override fun toString() = value // => prints as raw string, not PostalCode(value=10001)
}
 
val valid = PostalCode.of("10001")   // => Succeeds; valid.value = "10001"
// val bad = PostalCode.of("abc")    // => throws IllegalArgumentException
// Every PostalCode reference is structurally guaranteed valid — invariant held by type

using System.Text.RegularExpressions;                                 // => namespace/package import
 
// sealed record: immutable after construction; static factory for fluent API
public sealed record PostalCode                                       // => record PostalCode
{
    private static readonly Regex Us = new(@"^\d{5}(-\d{4})?$", RegexOptions.Compiled); // => Us initialised
    // => static readonly: compiled once; RegexOptions.Compiled = faster repeat usage
 
    public string Value { get; } // => get-only: no setter; immutable after ctor
 
    public PostalCode(string value)                                   // => PostalCode method
    {
        // => Validate before assigning; invalid cannot escape constructor
        if (!Us.IsMatch(value ?? string.Empty))                       // => precondition check
            throw new ArgumentException($"Invalid US postal code: {value}"); // => throws if guard fails
        Value = value; // => Only assigned when pattern matched
    }
 
    public static PostalCode Of(string v) => new(v);                  // => Of method
    // => PostalCode.Of("10001") — static factory; identical validation path
 
    public override string ToString() => Value; // => "10001"
}
 
var valid = PostalCode.Of("10001");  // => Value = "10001"
// var bad = PostalCode.Of("abc");   // => throws ArgumentException
// Downstream code needs no format-check — the type proves validity

// Leaf Value Objects: each wraps a validated primitive
public record Street(String value) {                                  // => record Street
    public Street { // => compact constructor validates in-place
        if (value == null || value.isBlank()) throw new IllegalArgumentException("Street required"); // => throws if guard fails
        // => blank street is a domain error; rejected at the Street boundary
    }
}
 
public record City(String value) {                                    // => record City
    public City { // => compact constructor
        if (value == null || value.isBlank()) throw new IllegalArgumentException("City required"); // => throws if guard fails
        // => same pattern: invalid city cannot exist as a City object
    }
}
 
// PostalCode from Example 4 — already validates regex
// Composed VO: valid Address proves valid Street, City, and PostalCode
public record Address(Street street, City city, PostalCode postalCode) { // => record Address
    public Address {                                                  // => expression
        // => Null check at composition level; each sub-VO validated itself
        if (street == null || city == null || postalCode == null)     // => precondition check
            throw new IllegalArgumentException("All address fields required"); // => throws if guard fails
        // => If street/city/postalCode were constructed, they are already valid
    }
}
 
Address addr = new Address(                                           // => expression
    new Street("123 Main St"),     // => Street validated: non-blank
    new City("Springfield"),       // => City validated: non-blank
    PostalCode.of("10001")         // => PostalCode validated: regex
); // => addr is fully valid; no further checks needed anywhere

// Leaf VOs: data classes with init validation
data class Street(val value: String) {                                // => class Street
    init { require(value.isNotBlank()) { "Street required" } }        // => value.isNotBlank() called
    // => require throws IllegalArgumentException on blank
}
data class City(val value: String) {                                  // => class City
    init { require(value.isNotBlank()) { "City required" } }          // => value.isNotBlank() called
    // => each VO guards its own invariant
}
 
// Composed VO: structural equality covers all nested fields via data class
data class Address(val street: Street, val city: City, val postalCode: PostalCode) { // => class Address
    init {                                                            // => expression
        // => Kotlin's require checks null via non-null types; this guards logical completeness
        require(street.value.isNotBlank() && city.value.isNotBlank()) { "All fields required" } // => precondition check
        // => postalCode already validated; composition cascades correctness
    }
}
 
val address = Address(                                                // => address initialised
    Street("123 Main St"),   // => validated non-blank
    City("Springfield"),     // => validated non-blank
    PostalCode.of("10001")   // => validated regex
) // => address is sound; every field proven valid by its own constructor

// Leaf VOs: records with validation in constructor
public record Street(string Value)                                    // => record Street
// => begins block
{
    public Street(string value) : this(value)                         // => Street method
    // => begins block
    {
        if (string.IsNullOrWhiteSpace(value)) throw new ArgumentException("Street required"); // => throws if guard fails
        // => rejects blank; primary ctor sets Value
    // => ends block
    }
// => ends block
}
public record City(string Value)                                      // => record City
// => begins block
{
    public City(string value) : this(value)                           // => City method
    // => begins block
    {
        if (string.IsNullOrWhiteSpace(value)) throw new ArgumentException("City required"); // => throws if guard fails
        // => same guard pattern for consistency
    // => ends block
    }
}
 
// Composed VO: == operator compares all three nested records structurally
public record Address(Street Street, City City, PostalCode PostalCode) // => record Address
{
    public Address(Street street, City city, PostalCode postalCode) : this(street, city, postalCode) // => Address method
    {
        // => null-guard; sub-VOs already validated their own values
        ArgumentNullException.ThrowIfNull(street);                    // => ArgumentNullException.ThrowIfNull() called
        ArgumentNullException.ThrowIfNull(city);                      // => ArgumentNullException.ThrowIfNull() called
        ArgumentNullException.ThrowIfNull(postalCode);                // => ArgumentNullException.ThrowIfNull() called
    }
}
 
var address = new Address(                                            // => address initialised
    new Street("123 Main St"),    // => validated: non-blank
    new City("Springfield"),      // => validated: non-blank
    PostalCode.Of("10001")        // => validated: regex
); // => address fully valid; downstream code reads fields without defensive checks

import java.util.UUID;                                                // => namespace/package import
 
// Entity: identity is the anchor; state changes do not alter identity
// => id is final; total and status are mutable — that is the correct split
public class Order {                                                  // => Order field
    private final OrderId id;        // => final: identity never changes after construction
    private Money total;             // => mutable: total grows as lines are added
    private OrderStatus status;      // => mutable: moves through lifecycle states
 
    public Order(OrderId id, Money initialTotal) {                    // => Order method
        this.id     = id;                         // => identity locked here, forever
        this.total  = initialTotal;               // => initial state; mutable via behaviour methods
        this.status = OrderStatus.PENDING;        // => all orders begin in PENDING state
    }
 
    public OrderId     getId()     { return id; }     // => expose identity for reference
    public Money       getTotal()  { return total; }  // => read current state
    public OrderStatus getStatus() { return status; } // => read current lifecycle position
}
 
// OrderId is itself a Value Object — typed identity
public record OrderId(UUID value) {                                   // => record OrderId
    // => record provides structural equality; two OrderId with same UUID are equal
    public static OrderId generate() { return new OrderId(UUID.randomUUID()); } // => generate method
    // => static factory: creates a globally unique identity
}
 
OrderId  id    = OrderId.generate();                         // => e.g. OrderId[value=3fa8...]
Order    order = new Order(id, new Money(new java.math.BigDecimal("0"), "USD")); // => math.BigDecimal() called
// => order.id is permanent; order.total and order.status will change over its lifetime

import java.util.UUID                                                 // => namespace/package import
 
// Entity: use class not data class — data class would compare all fields, breaking entity semantics
// => equals() by id only (overridden below); data class equals() by all fields is WRONG for entities
class Order(                                                          // => class Order
    val id: OrderId,          // => val: identity immutable; this is what "same order" means
    initialTotal: Money       // => constructor param; stored as var property below
) {                                                                   // => expression
    var total: Money = initialTotal  // => var: mutable state
        private set                  // => only mutated through behaviour methods in this class
    var status: OrderStatus = OrderStatus.PENDING // => starts PENDING
        private set                                                   // => expression
 
    // Identity-based equality: two Order references with same id are equal
    override fun equals(other: Any?) = other is Order && id == other.id // => equals method
    override fun hashCode() = id.hashCode() // => hash matches equals; id-only
}
 
@JvmInline value class OrderId(val value: UUID) {                     // => class OrderId
    // => value class: zero-overhead wrapper; erased to UUID at runtime
    companion object { fun generate() = OrderId(UUID.randomUUID()) }  // => UUID.randomUUID() called
    // => generate() is the one creation path; callers never see raw UUIDs
}
 
val order = Order(OrderId.generate(), Money(java.math.BigDecimal.ZERO, "USD")) // => order initialised
// => order.id is fixed; order.total and order.status change through lifecycle

using System;                                                         // => namespace/package import
 
// Entity: class not record — record would use structural equality, wrong for entities
// => override Equals to compare by id only; class default is reference equality
public class Order                                                    // => class Order
{
    public OrderId      Id     { get; }              // => init-only: identity locked in ctor
    public Money        Total  { get; private set; } // => private set: mutable via methods only
    public OrderStatus  Status { get; private set; } = OrderStatus.Pending; // => Status field
    // => Defaults to Pending; private set enforces encapsulation
 
    public Order(OrderId id, Money initialTotal)                      // => Order method
    {
        Id    = id;           // => identity locked; no setter to reassign it
        Total = initialTotal; // => initial state; changes via behaviour methods
    }
 
    // Identity-based equality: same id = same order, regardless of current state
    public override bool Equals(object? obj) => obj is Order o && Id == o.Id; // => Equals method
    public override int  GetHashCode()       => Id.GetHashCode(); // => id-based hash
}
 
public record OrderId(Guid Value)                                     // => record OrderId
{
    // => record gives structural ==; two OrderId with same Guid are equal
    public static OrderId Generate() => new(Guid.NewGuid()); // => new unique id
}
 
var order = new Order(OrderId.Generate(), new Money(0m, "USD"));      // => order initialised
// => order.Id is fixed; order.Total and order.Status change through lifecycle

import java.util.Objects;                                             // => namespace/package import
 
public class Customer {                                               // => Customer field
    private final CustomerId id; // => identity; used exclusively in equals/hashCode
    private String name;          // => mutable state — NOT part of equality
    private EmailAddress email;   // => mutable state — NOT part of equality
 
    public Customer(CustomerId id, String name, EmailAddress email) { // => Customer method
        this.id    = id;    // => identity locked
        this.name  = name;  // => initial state; can change without affecting equality
        this.email = email; // => initial state; can change without affecting equality
    }
 
    // Equality by id ONLY — not name, not email
    @Override public boolean equals(Object o) {                       // => expression
        if (!(o instanceof Customer c)) return false;                 // => precondition check
        return id.equals(c.id); // => only id compared; name/email irrelevant to identity
    }
    @Override public int hashCode() { return Objects.hash(id); } // => hash from id only
 
    public void rename(String newName) { this.name = newName; } // => state change; equality unchanged
    public CustomerId getId() { return id; }                          // => getId method
}
 
// Demonstration: same id, different state — entities are still equal
var sharedId = new CustomerId(java.util.UUID.randomUUID()); // => one UUID shared by both
Customer c1 = new Customer(sharedId, "Alice",       new EmailAddress("a@b.com")); // => expression
Customer c2 = new Customer(sharedId, "Alice Smith", new EmailAddress("asmith@b.com")); // => expression
// => c1 and c2 have different names and emails
boolean equal = c1.equals(c2); // => true — same id; state differences are irrelevant

// Kotlin: override equals() manually; do NOT use data class for entities
// => data class compares all fields — that is Value Object semantics, not Entity semantics
class Customer(                                                       // => class Customer
    val id: CustomerId, // => identity; val: immutable
    var name: String,   // => mutable state; var
    var email: EmailAddress // => mutable state; var
) {                                                                   // => expression
    override fun equals(other: Any?): Boolean {                       // => equals method
        if (other !is Customer) return false                          // => precondition check
        return id == other.id  // => id equality only; name and email excluded
    }
    override fun hashCode() = id.hashCode() // => consistent with equals
}
 
val sharedId = CustomerId(java.util.UUID.randomUUID()) // => one UUID
val c1 = Customer(sharedId, "Alice",       EmailAddress("a@b.com"))   // => c1 initialised
val c2 = Customer(sharedId, "Alice Smith", EmailAddress("asmith@b.com")) // => c2 initialised
println(c1 == c2)  // => true — same id; different names; identity wins

public class Customer                                                 // => class Customer
// => begins block
{
    public CustomerId   Id    { get; }               // => identity; immutable
    public string       Name  { get; private set; }  // => mutable state
    public EmailAddress Email { get; private set; }  // => mutable state
 
    public Customer(CustomerId id, string name, EmailAddress email)   // => Customer method
    // => begins block
    {
        Id    = id;    // => identity locked in constructor
        Name  = name;  // => initial state
        Email = email; // => initial state
    // => ends block
    }
 
    // Equality by id ONLY — name and email excluded from comparison
    public override bool Equals(object? obj) => obj is Customer c && Id == c.Id; // => Equals method
    public override int  GetHashCode()       => Id.GetHashCode(); // => id-based hash
 
    public void Rename(string newName) { Name = newName; } // => state change; equality unchanged
}
 
var sharedId = CustomerId.Generate(); // => one id shared by both instances
var c1 = new Customer(sharedId, "Alice",       new EmailAddress("a@b.com")); // => c1 initialised
var c2 = new Customer(sharedId, "Alice Smith", new EmailAddress("asmith@b.com")); // => c2 initialised
bool equal = c1.Equals(c2); // => true — same id; Name/Email differences ignored

public class Order {                                                  // => Order field
    private final OrderId id;    // => identity: immutable
    private Money total;          // => state: mutable, but only via methods below
    private OrderStatus status;   // => state: mutable, but only via methods below
 
    public Order(OrderId id, Money initialTotal) {                    // => Order method
        this.id     = id;                                             // => this.id assigned
        this.total  = initialTotal;                                   // => this.total assigned
        this.status = OrderStatus.PENDING; // => always starts PENDING
    }
 
    // Named behaviour: communicates intent and enforces lifecycle rule
    public void confirm() {                                           // => confirm method
        // => Guard: confirm() only valid from PENDING state
        if (status != OrderStatus.PENDING)                            // => precondition check
            throw new IllegalStateException("Cannot confirm order in state: " + status); // => throws if guard fails
        this.status = OrderStatus.CONFIRMED; // => state transition enforced here
        // => domain event could be collected here (see Example 25)
    }
 
    public void cancel() {                                            // => cancel method
        // => Cannot cancel a shipped order — domain invariant enforced in method
        if (status == OrderStatus.SHIPPED)                            // => precondition check
            throw new IllegalStateException("Cannot cancel a shipped order"); // => throws if guard fails
        this.status = OrderStatus.CANCELLED; // => only reachable if not SHIPPED
    }
 
    // No setStatus() — callers cannot bypass lifecycle rules
    public OrderId     getId()     { return id; }                     // => getId method
    public OrderStatus getStatus() { return status; }                 // => getStatus method
    public Money       getTotal()  { return total; }                  // => getTotal method
}
 
Order order = new Order(OrderId.generate(), new Money(new java.math.BigDecimal("50"), "USD")); // => OrderId.generate() called
order.confirm();  // => status becomes CONFIRMED; invariant checked
// order.setStatus(SHIPPED) — does not exist; cannot bypass confirm()

class Order(val id: OrderId, initialTotal: Money) {                   // => class Order
    var total: Money = initialTotal                                   // => expression
        private set           // => readable externally; writable only inside class
    var status: OrderStatus = OrderStatus.PENDING                     // => expression
        private set           // => no public setter; only behaviour methods can mutate
 
    fun confirm() {                                                   // => confirm method
        // => Enforce lifecycle: PENDING → CONFIRMED only
        check(status == OrderStatus.PENDING) { "Cannot confirm order in state: $status" } // => precondition check
        status = OrderStatus.CONFIRMED // => private set allows mutation from within
    }
 
    fun cancel() {                                                    // => cancel method
        // => Enforce lifecycle: cannot cancel SHIPPED
        check(status != OrderStatus.SHIPPED) { "Cannot cancel a shipped order" } // => precondition check
        status = OrderStatus.CANCELLED // => reached only if check() passes
    }
    // No setStatus — callers use confirm()/cancel(); invariants always enforced
}
 
val order = Order(OrderId.generate(), Money(java.math.BigDecimal("50"), "USD")) // => order initialised
order.confirm() // => status = CONFIRMED; invariant checked inside confirm()

public class Order                                                    // => class Order
// => Entity class: uses reference equality by default; Equals overridden to use Id
{
    public OrderId      Id     { get; }                               // => Id field
    // => get-only: Id locked at construction; identity never changes
    public Money        Total  { get; private set; } // => private set; mutable via methods
    // => Mutable state: Total changes as lines are added; private set enforces encapsulation
    public OrderStatus  Status { get; private set; } = OrderStatus.Pending; // => Status field
    // => defaults to Pending; private set prevents external mutation
 
    public Order(OrderId id, Money initialTotal) { Id = id; Total = initialTotal; } // => Order method
    // => Constructor: sets both required fields; Status defaults to Pending automatically
 
    public void Confirm()                                             // => Confirm method
    // => Named method: communicates intent; can add events, logging, metrics here
    {
        // => Guard: only PENDING orders can be confirmed
        if (Status != OrderStatus.Pending)                            // => precondition check
            throw new InvalidOperationException($"Cannot confirm order in state {Status}"); // => throws if guard fails
        // => $"...{Status}" includes current status in the message for diagnostics
        Status = OrderStatus.Confirmed; // => private set accessible within the class
        // => Transition happens after guard; no partial state possible
    }
 
    public void Cancel()                                              // => Cancel method
    // => Named method: one place to add "why was this cancelled?" auditing in future
    {
        // => Guard: SHIPPED orders cannot be cancelled
        if (Status == OrderStatus.Shipped)                            // => precondition check
            throw new InvalidOperationException("Cannot cancel a shipped order"); // => throws if guard fails
        // => All other statuses (Pending, Confirmed) are cancellable
        Status = OrderStatus.Cancelled; // => reachable only if not SHIPPED
    }
    // No SetStatus() — public API is confirm/cancel; invariants always run
}
 
var order = new Order(OrderId.Generate(), new Money(50m, "USD"));     // => order initialised
// => order.Status = Pending (default); order.Total = 50 USD
order.Confirm(); // => Status = Confirmed; lifecycle rule enforced

// Value Object: two instances with same data ARE the same thing
// => Money(10, "USD") and Money(10, "USD") are interchangeable — no tracking needed
public record Money(java.math.BigDecimal amount, String currency) {}  // => record Money
// => record provides structural equals/hashCode; correct for VO
 
// Entity: two instances with same data are NOT necessarily the same thing
// => Two bank accounts at $0 balance are different accounts — track by id
public class BankAccount {                                            // => BankAccount field
    private final AccountId id;    // => identity: THIS specific account
    private Money balance;          // => state: can change without affecting identity
 
    public BankAccount(AccountId id, Money initial) {                 // => BankAccount method
        this.id      = id;                                            // => this.id assigned
        this.balance = initial;                                       // => this.balance assigned
    }
 
    // Two $0 accounts are still two different accounts — never merge them
    @Override public boolean equals(Object o) {                       // => expression
        if (!(o instanceof BankAccount a)) return false;              // => precondition check
        return id.equals(a.id); // => only id; balance is irrelevant for identity
    }
    @Override public int hashCode() { return id.hashCode(); }         // => id.hashCode() called
}
 
// Rule of thumb: ask "if I replace this with an equal instance, does anything break?"
// => If yes → Entity (history matters)   If no → Value Object (interchangeable)

// Value Object: data class = structural equality = correct VO choice
data class Money(val amount: java.math.BigDecimal, val currency: String)
// => data class generates equals() comparing amount and currency — correct for VO
 
// Entity: class = reference equality by default; override to id-based equality
class BankAccount(val id: AccountId, initialBalance: Money) {
    var balance: Money = initialBalance
        private set  // => mutable state; but changing balance doesn't change which account
 
    override fun equals(other: Any?) = other is BankAccount && id == other.id
    override fun hashCode() = id.hashCode()
    // => Two $0 accounts at same bank are still different accounts — id distinguishes them
}
 
// Rule of thumb in Kotlin:
// data class → Value Object (structural equality, immutable val fields)
// class       → Entity (identity equality, mutable var state, override equals)

// Value Object: record = structural ==; correct for VO
public record Money(decimal Amount, string Currency);
// => record == compares Amount and Currency — Money(10m,"USD") == Money(10m,"USD")
 
// Entity: class = reference equality by default; override to id-based
public class BankAccount
{
    public AccountId Id      { get; }
    public Money     Balance { get; private set; } // => mutable state
 
    public BankAccount(AccountId id, Money initial) { Id = id; Balance = initial; }
 
    // Two $0 accounts are different — id is the only equality criterion
    public override bool Equals(object? obj) => obj is BankAccount a && Id == a.Id;
    public override int  GetHashCode()       => Id.GetHashCode();
    // => Changing Balance does not change which account this is
}
 
// Rule of thumb in C#:
// record → Value Object (structural equality provided by compiler)
// class  → Entity (identity equality via manual override)

// Static factory method: named, validated construction with descriptive errors
// => Factory can return subtypes, use caching, or throw domain-specific exceptions
public final class Quantity {                                         // => Quantity field
    private final int value; // => int value wrapped; always positive
 
    private Quantity(int value) { this.value = value; } // => private: factory is the only path
 
    public static Quantity of(int value) {                            // => of method
        // => Named validation; message references domain concept, not technical detail
        if (value <= 0) throw new IllegalArgumentException("Quantity must be positive, got: " + value); // => throws if guard fails
        return new Quantity(value); // => only reachable after validation passes
    }
 
    public int getValue() { return value; } // => read-only
    public Quantity add(Quantity other) {                             // => add method
        return new Quantity(this.value + other.value); // => produces new Quantity; addition always positive
    }
    @Override public String toString() { return String.valueOf(value); } // => "3"
}
 
Quantity q = Quantity.of(3);    // => Succeeds; q.getValue() = 3
// Quantity bad = Quantity.of(0); // => throws "Quantity must be positive, got: 0"
// private constructor: new Quantity(3) is compile error from outside the class

// companion object factory: private constructor forces use of of()
class Quantity private constructor(val value: Int) {                  // => class Quantity
    // => private constructor: no new Quantity(0) from outside
    companion object {                                                // => expression
        fun of(value: Int): Quantity {                                // => of method
            require(value > 0) { "Quantity must be positive, got: $value" } // => precondition check
            // => require throws IllegalArgumentException with the lambda message
            return Quantity(value) // => private ctor accessible from companion
        }
    }
    operator fun plus(other: Quantity) = Quantity(value + other.value) // => operator overload for +
    override fun toString() = value.toString() // => "3"
}
 
val q = Quantity.of(3)   // => Succeeds; q.value = 3
// val bad = Quantity.of(0)  // => throws IllegalArgumentException
// operator: Quantity.of(2) + Quantity.of(3) = Quantity(5) — idiomatic Kotlin

// sealed record with private constructor and static factory
public sealed record Quantity                                         // => record Quantity
{
    public int Value { get; } // => get-only; no setter; immutable after factory
 
    private Quantity(int value) { Value = value; } // => private: factory is the one path
 
    public static Quantity Of(int value)                              // => Of method
    {
        // => Domain-language error message; makes failure traceable to business rule
        if (value <= 0) throw new ArgumentException($"Quantity must be positive, got: {value}"); // => throws if guard fails
        return new Quantity(value); // => only reached after validation
    }
 
    public Quantity Add(Quantity other) => new(Value + other.Value);  // => Add method
    // => produces new Quantity; no mutation; sum always positive (both inputs positive)
 
    public override string ToString() => Value.ToString(); // => "3"
}
 
var q = Quantity.Of(3);   // => Value = 3
// var bad = Quantity.Of(0); // => throws ArgumentException
// private ctor: new Quantity(3) is a compile error outside the class

public class Order {                                                  // => Order field
    private final OrderId id;     // => identity
    private Money total;           // => private; accessed only via getTotal()
    private OrderStatus status;    // => private; transitions via named methods
 
    public Order(OrderId id) {                                        // => Order method
        this.id     = id;                                             // => this.id assigned
        this.total  = Money.zero("USD"); // => factory method; starts at zero
        this.status = OrderStatus.PENDING;                            // => this.status assigned
    // => ends block
    }
 
    // Intention-revealing accessor: name says what it means, not how it's stored
    public Money       getTotal()  { return total; }   // => readable; not settable
    public OrderStatus getStatus() { return status; }  // => readable; not settable
    public OrderId     getId()     { return id; }      // => readable; immutable
 
    // Encapsulated mutation: logic lives here, not scattered in callers
    public void addToTotal(Money extra) {                             // => addToTotal method
        // => currency-matching enforced by Money.add(); invariant inside VO
        this.total = this.total.add(extra); // => replaces total with new Money instance
    }
 
    private void transitionTo(OrderStatus next) {                     // => transitionTo method
        // => private helper enforces allowed transitions — callers use public methods
        this.status = next;                                           // => this.status assigned
    }
 
    public void confirm() {                                           // => confirm method
        if (status != OrderStatus.PENDING)                            // => precondition check
            throw new IllegalStateException("Only PENDING orders can be confirmed"); // => throws if guard fails
        transitionTo(OrderStatus.CONFIRMED); // => private helper called internally
    }
}

class Order(val id: OrderId) {                                        // => class Order
    // => backing properties private; exposed via getters with intention-revealing names
    private var _total: Money = Money(java.math.BigDecimal.ZERO, "USD") // => method declaration
    private var _status: OrderStatus = OrderStatus.PENDING            // => expression
 
    val total:  Money       get() = _total   // => read-only public getter
    val status: OrderStatus get() = _status  // => read-only public getter
 
    fun addToTotal(extra: Money) {                                    // => addToTotal method
        _total = _total.add(extra) // => encapsulated; no external mutation of _total
    // => ends block
    }
 
    fun confirm() {                                                   // => confirm method
        check(_status == OrderStatus.PENDING) { "Only PENDING orders can be confirmed" } // => precondition check
        _status = OrderStatus.CONFIRMED // => only reachable if check passes
    }
    // No _total = ... from outside the class; Kotlin val getter prevents it
}

public class Order                                                    // => class Order
// => begins block
{
    private Money       _total;  // => private backing field; only mutated through AddToTotal()
    private OrderStatus _status; // => private backing field; only mutated through Confirm()
 
    public OrderId      Id     { get; }                      // => immutable; public read-only
    public Money        Total  => _total;                     // => expression-bodied getter; readonly projection
    public OrderStatus  Status => _status;                    // => expression-bodied getter; readonly projection
    // => No public setter for Total or Status; only domain methods may mutate backing fields
 
    public Order(OrderId id)                                          // => Order method
    {
        Id      = id;                                                 // => Id assigned
        // => Id locked at construction; no reassignment possible (get-only property)
        _total  = new Money(0m, "USD"); // => starts at zero
        // => Initial total is zero; grows via AddToTotal()
        _status = OrderStatus.Pending;                                // => _status assigned
        // => All orders start Pending; lifecycle methods control transitions
    }
 
    public void AddToTotal(Money extra)                               // => AddToTotal method
    {
        _total = _total.Add(extra); // => encapsulated mutation; callers cannot bypass
        // => Add returns a new Money instance; _total is reassigned, not mutated in place
    }
 
    public void Confirm()                                             // => Confirm method
    {
        if (_status != OrderStatus.Pending)                           // => precondition check
            throw new InvalidOperationException("Only Pending orders can be confirmed"); // => throws if guard fails
        // => Guard: CONFIRMED → re-confirm is rejected; PENDING is the only valid source state
        _status = OrderStatus.Confirmed; // => private field writable here; not via property
        // => Callers reading Status property see Confirmed; they cannot set it directly
    }
}

// Tell-don't-ask: Order computes its own total from lines — callers do not extract and sum
public class Order {                                                  // => Order field
    private final OrderId id;                                         // => id field
    private final java.util.List<OrderLine> lines = new java.util.ArrayList<>(); // => method declaration
    private OrderStatus status = OrderStatus.PENDING;                 // => status declared
 
    public Order(OrderId id) { this.id = id; }                        // => Order method
 
    // WRONG (ask): external code asks for lines, then computes total
    // callers would do: order.getLines().stream().map(l -> l.price).reduce(...)
    // => logic duplicated across callers; no single place to change
 
    // RIGHT (tell): Order tells itself to compute total — logic stays inside
    public Money calculateTotal() {                                   // => calculateTotal method
        return lines.stream()                                         // => returns lines.stream()
            .map(OrderLine::subtotal)  // => delegate to child; each line knows its own subtotal
            .reduce(Money.zero("USD"), Money::add); // => fold into running total
        // => caller receives result; never sees individual lines for calculation purposes
    }
 
    public void addLine(ProductId pid, Quantity qty, Money price) {   // => addLine method
        lines.add(new OrderLine(OrderLineId.generate(), pid, qty, price)); // => lines.add() called
        // => Order creates child; callers do not construct OrderLine directly
    }
 
    public java.util.List<OrderLine> getLines() {                     // => getLines method
        return java.util.Collections.unmodifiableList(lines);         // => returns java.util.Collections.unmodifi
        // => read-only view; callers can read but not mutate the list
    }
}

class Order(val id: OrderId) {                                        // => class Order
    private val _lines = mutableListOf<OrderLine>() // => private mutable backing list
    val lines: List<OrderLine> get() = _lines.toList() // => defensive copy; caller gets snapshot
 
    // Tell-don't-ask: Order computes total; callers do not iterate lines externally
    fun calculateTotal(): Money =                                     // => calculateTotal method
        _lines.fold(Money(java.math.BigDecimal.ZERO, "USD")) { acc, line -> // => _lines.fold() called
            acc.add(line.subtotal()) // => each line delegates to itself (tell-don't-ask recursively)
        } // => returns total; caller never needs to know how lines are stored
 
    fun addLine(pid: ProductId, qty: Quantity, price: Money) {        // => addLine method
        _lines += OrderLine(OrderLineId.generate(), pid, qty, price)  // => _lines assigned
        // => Order owns child creation; caller provides data, Order creates the child
    }
}

public class Order                                                    // => class Order
{
    private readonly List<OrderLine> _lines = new();                  // => List method
    // => private list; external code cannot manipulate it directly
 
    public OrderId Id { get; }                                        // => Id field
    // => immutable identity
 
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();     // => IReadOnlyList method
    // => read-only view; callers can enumerate but not add/remove
 
    public Order(OrderId id) { Id = id; }                             // => Order method
 
    // Tell-don't-ask: ask Order for its total; don't ask for lines to compute it yourself
    public Money CalculateTotal() =>                                  // => CalculateTotal method
        _lines.Aggregate(new Money(0m, "USD"), (acc, line) => acc.Add(line.Subtotal())); // => _lines.Aggregate() called
        // => LINQ Aggregate folds lines into total; caller gets Money back; no line details needed
 
    public void AddLine(ProductId pid, Quantity qty, Money price)     // => AddLine method
    {
        _lines.Add(new OrderLine(OrderLineId.Generate(), pid, qty, price)); // => _lines.Add() called
        // => Order creates child; callers call AddLine with data, not with an OrderLine object
    }
}

import java.util.Objects;                                             // => namespace/package import
 
// Domain primitive: wraps String; adds domain meaning and validation
// => EmailAddress is not interchangeable with any String — type system enforces this
public final class EmailAddress {                                     // => EmailAddress field
    private final String value; // => normalised lowercase value
 
    public EmailAddress(String value) {                               // => EmailAddress method
        // => validate format; reject null and malformed emails at construction
        if (value == null || !value.contains("@") || value.length() < 3) // => precondition check
            throw new IllegalArgumentException("Invalid email: " + value); // => throws if guard fails
        this.value = value.toLowerCase(); // => normalise; consistent equality
    }
 
    public String getValue() { return value; } // => read-only accessor
    @Override public boolean equals(Object o) {                       // => expression
        if (!(o instanceof EmailAddress e)) return false;             // => precondition check
        return value.equals(e.value); // => structural equality
    }
    @Override public int hashCode() { return Objects.hash(value); }   // => Objects.hash() called
    @Override public String toString() { return value; } // => "alice@example.com"
}
 
// Usage: type system prevents passing a raw String where EmailAddress expected
// void sendWelcome(EmailAddress email) — compiler rejects sendWelcome("raw string")
EmailAddress email = new EmailAddress("Alice@Example.com"); // => "alice@example.com"
// sendWelcome(email) — correct; sendWelcome("alice@example.com") — compile error

// @JvmInline value class: zero-overhead wrapper; erased to String at runtime
@JvmInline value class EmailAddress(val value: String) {
    // => value class: no allocation overhead; wrapped value stored directly
    init {
        require(value.isNotBlank() && value.contains("@")) { "Invalid email: $value" }
        // => init block runs at construction; validation always applies
    }
}
 
// Usage: function signature is self-documenting and type-safe
fun sendWelcome(email: EmailAddress) { /* ... */ }
val email = EmailAddress("alice@example.com") // => validated at creation
// sendWelcome(email)               — correct
// sendWelcome("alice@example.com") — compile error: String is not EmailAddress

// readonly record struct: value semantics, zero heap allocation, structural equality
public readonly record struct EmailAddress                            // => record struct
{
    public string Value { get; } // => get-only; immutable after construction
 
    public EmailAddress(string value)                                 // => EmailAddress method
    {
        // => validate; reject null/blank/missing @
        if (string.IsNullOrWhiteSpace(value) || !value.Contains('@')) // => precondition check
            throw new ArgumentException($"Invalid email: {value}");   // => throws if guard fails
        Value = value.ToLowerInvariant(); // => normalise for consistent equality
    }
 
    public override string ToString() => Value; // => "alice@example.com"
}
 
// Function accepts EmailAddress, not string — compiler enforces at call site
void SendWelcome(EmailAddress email) { /* ... */ }                    // => expression
var email = new EmailAddress("Alice@Example.com"); // => Value = "alice@example.com"
// SendWelcome(email)                — correct
// SendWelcome("alice@example.com")  — compile error: string ≠ EmailAddress

import java.util.UUID;
 
// Separate record types for each aggregate's id
// => OrderId and CustomerId are structurally identical but type-incompatible
public record OrderId(UUID value) {
    public static OrderId generate() { return new OrderId(UUID.randomUUID()); }
    // => factory: ensures every id is a real UUID
}
 
public record CustomerId(UUID value) {
    public static CustomerId generate() { return new CustomerId(UUID.randomUUID()); }
    // => same UUID internally, but separate type from OrderId
}
 
// Usage: method signatures prevent id mix-up at compile time
public Order findOrder(OrderId id) { /* ... */ return null; } // => accepts only OrderId
// findOrder(new CustomerId(UUID.randomUUID())) — compile error: CustomerId ≠ OrderId
// findOrder(new OrderId(UUID.randomUUID()))    — correct
 
// Before typed ids: findOrder(UUID id) accepts any UUID — wrong ids compile silently

// @JvmInline value classes: zero-overhead; erased to UUID at runtime; distinct types at compile time
@JvmInline value class OrderId(val value: java.util.UUID) {           // => class OrderId
    companion object { fun generate() = OrderId(java.util.UUID.randomUUID()) } // => UUID.randomUUID() called
    // => generate() is the canonical factory
}
@JvmInline value class CustomerId(val value: java.util.UUID) {        // => class CustomerId
    companion object { fun generate() = CustomerId(java.util.UUID.randomUUID()) } // => UUID.randomUUID() called
    // => same UUID type inside, but CustomerId ≠ OrderId at the Kotlin type level
}
 
fun findOrder(id: OrderId): Order? = null  // => only OrderId accepted
// findOrder(CustomerId.generate()) — compile error
// findOrder(OrderId.generate())    — correct; no runtime cost from @JvmInline

// readonly record struct: value semantics, no heap allocation, type-distinct ids
public readonly record struct OrderId(Guid Value)                     // => record struct
// => begins block
{
    public static OrderId Generate() => new(Guid.NewGuid()); // => canonical factory
}
public readonly record struct CustomerId(Guid Value)                  // => record struct
{
    public static CustomerId Generate() => new(Guid.NewGuid()); // => separate type
}
 
Order? FindOrder(OrderId id) => null; // => only OrderId compiles here
// FindOrder(CustomerId.Generate()) — compile error: CustomerId ≠ OrderId
// FindOrder(OrderId.Generate())    — correct; record struct = zero allocation

// Enum as domain concept: exhaustive; type-safe; no invalid status possible
// => Cannot pass "SHPIED" (typo) — only enum constants compile
public enum OrderStatus {
    PENDING,    // => Order created; awaiting confirmation
    CONFIRMED,  // => Payment authorised; awaiting shipment
    SHIPPED,    // => Physical goods dispatched
    CANCELLED;  // => Order cancelled before or after confirmation
 
    // Domain behaviour inside the enum: isTerminal tells callers which states end the lifecycle
    public boolean isTerminal() {
        return this == SHIPPED || this == CANCELLED;
        // => PENDING and CONFIRMED are interim; SHIPPED and CANCELLED are final
    }
}
 
// Usage: switch is exhaustive when all cases are handled
OrderStatus s = OrderStatus.PENDING;
boolean terminal = s.isTerminal(); // => false — PENDING is not terminal
// String-based equivalent: switch("PENDNG") compiles — typo not caught; enum prevents this

// Kotlin sealed class or enum; enum is simpler for fixed finite states
enum class OrderStatus {                                              // => enum class
    PENDING,    // => created; awaiting confirmation
    CONFIRMED,  // => payment authorised
    SHIPPED,    // => dispatched
    CANCELLED;  // => terminal; no further transitions
 
    fun isTerminal() = this == SHIPPED || this == CANCELLED           // => isTerminal method
    // => business rule embedded in enum; callers ask status.isTerminal() — tell-don't-ask
}
 
// Kotlin when is exhaustive on enum — compiler warns on missing cases
fun describe(s: OrderStatus) = when (s) {                             // => describe method
    OrderStatus.PENDING   -> "Awaiting confirmation"  // => all cases covered
    OrderStatus.CONFIRMED -> "Ready to ship"                          // => expression
    OrderStatus.SHIPPED   -> "On its way"                             // => expression
    OrderStatus.CANCELLED -> "Order cancelled"                        // => expression
} // => no else needed; missing case = compile warning

// C# enum: strongly typed; switch expressions can be exhaustive with default handling
public enum OrderStatus                                               // => enum OrderStatus
{
    Pending   = 1, // => start at 1; avoids default(int) = 0 acting as Pending silently
    Confirmed = 2, // => payment confirmed
    Shipped   = 3, // => dispatched
    Cancelled = 4  // => terminal
}
 
// Extension method: domain behaviour near the enum
public static class OrderStatusExtensions                             // => class OrderStatusExtensions
{
    public static bool IsTerminal(this OrderStatus s) =>              // => IsTerminal method
        s is OrderStatus.Shipped or OrderStatus.Cancelled;            // => expression
        // => C# 9 pattern: readable OR pattern in is-expression
}
 
// Usage
var s = OrderStatus.Pending;                                          // => s initialised
bool terminal = s.IsTerminal(); // => false
// switch expression enforces handling: compiler warning if a case is missing

import java.util.*; // => List, ArrayList, Collections — all standard library
 
// Aggregate Root: sole entry point into the Order cluster
// => No external code directly constructs or modifies OrderLine
public class Order { // => class not record: mutable state; identity-based equality
    private final OrderId id;                                   // => final: identity locked
    private final List<OrderLine> lines = new ArrayList<>();    // => private; root owns children
    private Address shippingAddress;                             // => Value Object child; replaceable
    private OrderStatus status = OrderStatus.PENDING;           // => starts PENDING; transitions via methods
 
    public Order(OrderId id, Address shippingAddress) {               // => Order method
        this.id              = id;              // => identity locked in constructor
        this.shippingAddress = shippingAddress; // => initial Value Object; may be updated
    }
 
    // External code adds lines through this method — never by creating OrderLine directly
    public void addLine(ProductId productId, Quantity quantity, Money unitPrice) { // => addLine method
        // => Root enforces invariant before creating child
        if (status != OrderStatus.PENDING)      // => lifecycle gate: only PENDING accepts new lines
            throw new IllegalStateException("Cannot add lines to non-pending order"); // => domain rule as exception
        OrderLineId lineId = OrderLineId.generate();  // => Root generates child's identity
        lines.add(new OrderLine(lineId, productId, quantity, unitPrice)); // => Root creates and owns child
    }
 
    public Money calculateTotal() { // => tell-don't-ask: caller gets total; never iterates lines
        return lines.stream().map(OrderLine::subtotal)  // => each line computes its subtotal
            .reduce(Money.zero("USD"), Money::add);      // => fold: accumulate into running total
    }
 
    public List<OrderLine> getLines() { return Collections.unmodifiableList(lines); } // => getLines method
    // => unmodifiable view: callers can read but not mutate the list
    public OrderId getId() { return id; } // => expose identity for repository lookup
}
 
// Package-private: external code outside the aggregate package cannot construct OrderLine
class OrderLine { // => package-private class: invisible outside domain.order package
    private final OrderLineId id;       // => final: line identity immutable
    private final ProductId productId;  // => which product
    private final Quantity quantity;    // => how many
    private final Money unitPrice;      // => price per unit at time of addition
 
    OrderLine(OrderLineId id, ProductId productId, Quantity quantity, Money unitPrice) { // => OrderLine() called
        // => package-private constructor: only Order (same package) can call this
        this.id = id; this.productId = productId;                     // => this.id assigned
        this.quantity = quantity; this.unitPrice = unitPrice; // => all fields set; no setters
    }
 
    Money subtotal() { return unitPrice.multiply(quantity.getValue()); } // => unitPrice.multiply() called
    // => line computes its own subtotal — tell-don't-ask within the aggregate
}

class Order(val id: OrderId, shippingAddress: Address) {              // => class Order
    private val _lines = mutableListOf<OrderLine>() // => private mutable list
    val lines: List<OrderLine> get() = _lines.toList() // => defensive copy on each read
 
    var status: OrderStatus = OrderStatus.PENDING                     // => expression
        private set // => only aggregate root methods can change status
 
    fun addLine(productId: ProductId, quantity: Quantity, unitPrice: Money) { // => addLine method
        // => invariant: only PENDING orders accept new lines
        check(status == OrderStatus.PENDING) { "Cannot add lines to non-pending order" } // => precondition check
        _lines += OrderLine(OrderLineId.generate(), productId, quantity, unitPrice) // => _lines assigned
        // => Root creates child with generated id; external code cannot create OrderLine
    }
 
    fun calculateTotal(): Money =                                     // => calculateTotal method
        _lines.fold(Money(java.math.BigDecimal.ZERO, "USD")) { acc, line -> // => _lines.fold() called
            acc.add(line.subtotal()) // => delegate to child; aggregate folds results
        }
}
 
// internal: visible only within the module; not accessible from outside the aggregate module
internal class OrderLine(  // => internal: module-scoped; not in public API
    val id: OrderLineId,    // => identity; immutable val
    val productId: ProductId, // => which product
    val quantity: Quantity,   // => how many
    val unitPrice: Money      // => price per unit at time of line creation
) {                                                                   // => expression
    fun subtotal(): Money = unitPrice.multiply(quantity.value) // => line computes its own subtotal
    // => tell-don't-ask: caller asks for subtotal; never asks for fields to compute it
}

public class Order // => class not record: mutable state; override Equals for id-based equality
// => begins block
{
    private readonly List<OrderLine> _lines = new(); // => private; root controls membership
    public OrderId     Id     { get; }               // => immutable identity
    public OrderStatus Status { get; private set; } = OrderStatus.Pending; // => starts Pending
 
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();     // => IReadOnlyList method
    // => read-only interface: callers can read, not mutate
 
    public Order(OrderId id) { Id = id; } // => identity locked; no other constructor overload
 
    public void AddLine(ProductId productId, Quantity quantity, Money unitPrice) // => AddLine method
    // => begins block
    {
        // => invariant enforced before creating child
        if (Status != OrderStatus.Pending)          // => lifecycle gate: only Pending accepts lines
            throw new InvalidOperationException("Cannot add lines to non-pending order"); // => domain rule
        _lines.Add(new OrderLine(OrderLineId.Generate(), productId, quantity, unitPrice)); // => _lines.Add() called
        // => Root creates and owns the child; callers only provide data, not an OrderLine instance
    }
 
    public Money CalculateTotal() =>                                  // => CalculateTotal method
        _lines.Aggregate(new Money(0m, "USD"), (acc, line) => acc.Add(line.Subtotal())); // => _lines.Aggregate() called
        // => fold lines into total; all line logic stays in OrderLine.Subtotal()
}
 
// internal: only accessible within this assembly (same as the aggregate)
internal sealed class OrderLine                                       // => class OrderLine
{
    public OrderLineId Id         { get; }                            // => Id field
    public ProductId   ProductId  { get; }                            // => ProductId field
    public Quantity    Quantity   { get; }                            // => Quantity field
    public Money       UnitPrice  { get; }                            // => UnitPrice field
 
    internal OrderLine(OrderLineId id, ProductId productId, Quantity quantity, Money unitPrice) // => OrderLine method
    {
        Id = id; ProductId = productId; Quantity = quantity; UnitPrice = unitPrice; // => Id assigned
        // => internal constructor: only Order (same assembly) can create OrderLine
    }
 
    internal Money Subtotal() => UnitPrice.Multiply(Quantity.Value); // => line computes itself
}

public class Order { // => Aggregate Root; owns invariants for the whole cluster
    private static final int MAX_LINES = 50; // => business rule: orders capped at 50 lines
    private final OrderId id;                // => identity; final
    private final List<OrderLine> lines = new ArrayList<>(); // => mutable child collection
    private OrderStatus status = OrderStatus.PENDING;        // => lifecycle state
 
    public Order(OrderId id) { this.id = id; } // => minimal constructor; no other arg needed here
 
    public void addLine(ProductId productId, Quantity quantity, Money unitPrice) { // => addLine method
        // => Cross-child invariant 1: order must be in a state that accepts new lines
        if (status != OrderStatus.PENDING)    // => status check before any mutation
            throw new IllegalStateException("Non-pending order cannot accept new lines"); // => domain rule
        // => Cross-child invariant 2: cannot exceed maximum line count
        if (lines.size() >= MAX_LINES)        // => size check before adding
            throw new IllegalStateException("Order cannot exceed " + MAX_LINES + " lines"); // => domain cap
        lines.add(new OrderLine(OrderLineId.generate(), productId, quantity, unitPrice)); // => lines.add() called
        // => Child added only after both invariants pass; cluster stays consistent
    }
 
    public void confirm() {                                           // => confirm method
        // => Cross-child invariant: cannot confirm empty order
        if (lines.isEmpty()) throw new IllegalStateException("Cannot confirm order with no lines"); // => throws if guard fails
        if (status != OrderStatus.PENDING) throw new IllegalStateException("Only PENDING orders can be confirmed"); // => throws if guard fails
        status = OrderStatus.CONFIRMED; // => all invariants passed; transition is safe
    }
}

class Order(val id: OrderId) {
    // => Primary constructor: id is a val property; immutable after construction
    companion object { const val MAX_LINES = 50 } // => named constant; domain rule is visible
    // => companion object: Kotlin's static scope; MAX_LINES accessible as Order.MAX_LINES
    private val _lines = mutableListOf<OrderLine>()
    // => Private mutable list; backing storage for the child entity collection
    var status: OrderStatus = OrderStatus.PENDING; private set
    // => Starts PENDING; private set: callers can read but not directly assign status
 
    fun addLine(productId: ProductId, quantity: Quantity, unitPrice: Money) {
        // => Invariant 1: lifecycle gate
        check(status == OrderStatus.PENDING) { "Non-pending order cannot accept new lines" }
        // => check() throws IllegalStateException if status is not PENDING
        // => Invariant 2: size limit — cross-child rule owned by root
        check(_lines.size < MAX_LINES) { "Order cannot exceed $MAX_LINES lines" }
        // => Size check: _lines.size returns current count; < MAX_LINES is the constraint
        _lines += OrderLine(OrderLineId.generate(), productId, quantity, unitPrice)
        // => Both checks passed; child safely added
        // => += is shorthand for _lines.add(); new OrderLine created with generated id
    }
 
    fun confirm() {
        // => Cross-child invariant: at least one line required
        check(_lines.isNotEmpty()) { "Cannot confirm order with no lines" }
        // => isNotEmpty(): returns true if _lines has at least one element
        check(status == OrderStatus.PENDING) { "Only PENDING orders can be confirmed" }
        // => Second guard: status must still be PENDING when confirm() is called
        status = OrderStatus.CONFIRMED
        // => private set accessible within Order; external code cannot set this directly
    }
}

public class Order                                                    // => class Order
{
    private const int MaxLines = 50; // => named constant; documents the business rule
    private readonly List<OrderLine> _lines = new();                  // => List method
    // => Private mutable backing list; external code gets read-only view only
    public OrderId     Id     { get; }                                // => Id field
    // => Identity: set in constructor, never reassigned
    public OrderStatus Status { get; private set; } = OrderStatus.Pending; // => Status field
    // => Starts Pending; private set ensures only Order methods can transition status
 
    public Order(OrderId id) { Id = id; }                             // => Order method
    // => New orders start with empty line list and Pending status
 
    public void AddLine(ProductId productId, Quantity quantity, Money unitPrice) // => AddLine method
    {
        // => Invariant 1: status gate before modifying the cluster
        if (Status != OrderStatus.Pending)                            // => precondition check
            throw new InvalidOperationException("Non-pending order cannot accept new lines"); // => throws if guard fails
        // => Confirmed or shipped orders cannot grow; only Pending accepts new lines
        // => Invariant 2: size limit enforced by root; no individual line knows about this
        if (_lines.Count >= MaxLines)                                 // => precondition check
            throw new InvalidOperationException($"Order cannot exceed {MaxLines} lines"); // => throws if guard fails
        // => 50 is the business rule; MaxLines documents why, not just what
        _lines.Add(new OrderLine(OrderLineId.Generate(), productId, quantity, unitPrice)); // => _lines.Add() called
        // => OrderLine created by root with a new generated id; caller never constructs OrderLine directly
    }
 
    public void Confirm()                                             // => Confirm method
    {
        // => Cross-child invariant: non-empty order required before confirmation
        if (_lines.Count == 0)  throw new InvalidOperationException("Cannot confirm empty order"); // => throws if guard fails
        // => Root checks aggregate-level invariant: one or more lines required
        if (Status != OrderStatus.Pending) throw new InvalidOperationException("Only Pending orders can be confirmed"); // => throws if guard fails
        // => Lifecycle guard: only Pending → Confirmed is allowed here
        Status = OrderStatus.Confirmed; // => all invariants satisfied; transition safe
    }
}

import java.util.*;                                                   // => namespace/package import
 
public class Order {                                                  // => Order field
    private final List<OrderLine> lines = new ArrayList<>(); // => mutable internal list
    private OrderStatus status = OrderStatus.PENDING;                 // => status declared
    // ...
 
    // WRONG: returns mutable list — caller can add/remove lines without root's knowledge
    // public List<OrderLine> getLines() { return lines; } // => anti-pattern; never do this
 
    // CORRECT: returns read-only view — caller can iterate, never mutate
    public List<OrderLine> getLines() {                               // => getLines method
        return Collections.unmodifiableList(lines);                   // => returns Collections.unmodifiableList(l
        // => UnsupportedOperationException if caller tries lines.add(...) or lines.remove(...)
    }
 
    // ALSO CORRECT: return defensive copy — caller gets a snapshot; no view into internals
    public List<OrderLine> getLinesSnapshot() {                       // => getLinesSnapshot method
        return new ArrayList<>(lines); // => copy; caller mutations don't affect the original
    }
 
    // External add goes through root — invariants enforced
    public void addLine(ProductId pid, Quantity qty, Money price) {   // => addLine method
        if (status != OrderStatus.PENDING) throw new IllegalStateException("Order not pending"); // => throws if guard fails
        lines.add(new OrderLine(OrderLineId.generate(), pid, qty, price)); // => lines.add() called
        // => only reachable after invariant check; aggregate stays consistent
    }
}

class Order(val id: OrderId) {                                        // => class Order
    private val _lines = mutableListOf<OrderLine>() // => private mutable; internal
    var status: OrderStatus = OrderStatus.PENDING; private set        // => expression
 
    // Exposes read-only List interface — caller cannot call add/remove
    val lines: List<OrderLine> get() = _lines.toList() // => defensive copy each time
    // => caller gets a snapshot; mutations to their copy don't affect _lines
 
    fun addLine(pid: ProductId, qty: Quantity, price: Money) {        // => addLine method
        check(status == OrderStatus.PENDING) { "Order not pending" }  // => precondition check
        _lines += OrderLine(OrderLineId.generate(), pid, qty, price)  // => _lines assigned
        // => only through this method; invariant always runs
    }
}

public class Order                                                    // => class Order
{
    private readonly List<OrderLine> _lines = new(); // => private; root owns this
    public OrderStatus Status { get; private set; } = OrderStatus.Pending; // => Status field
 
    // IReadOnlyList<T>: exposes Count and indexer but no Add/Remove/Clear
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();     // => IReadOnlyList method
    // => AsReadOnly() wraps _lines; changes to _lines are visible but callers cannot mutate
 
    // Alternatively: return an IEnumerable<OrderLine> for even more encapsulation
    // public IEnumerable<OrderLine> Lines => _lines; // => read-only; no Count without LINQ
 
    public void AddLine(ProductId pid, Quantity qty, Money price)     // => AddLine method
    {
        if (Status != OrderStatus.Pending)                            // => precondition check
            throw new InvalidOperationException("Order not pending"); // => throws if guard fails
        _lines.Add(new OrderLine(OrderLineId.Generate(), pid, qty, price)); // => _lines.Add() called
        // => invariant checked; child added through the root only
    }
}

// Application Service: one transaction = one aggregate; see Example 23 for full service
public class ConfirmOrderService {
    private final OrderRepository orderRepo;       // => loads/saves Order aggregate
    private final CustomerRepository customerRepo; // => separate aggregate; separate transaction
 
    public ConfirmOrderService(OrderRepository o, CustomerRepository c) {
        this.orderRepo   = o;
        this.customerRepo = c;
    }
 
    // WRONG: two aggregates in one transaction — tight coupling, hard to scale
    // public void confirmAndUpdateCustomer(OrderId oid, CustomerId cid) {
    //   Order o = orderRepo.findById(oid);    // => first aggregate loaded
    //   Customer c = customerRepo.findById(cid); // => second aggregate loaded
    //   o.confirm();
    //   c.recordPurchase(o.getTotal()); // => BOTH saved in one transaction — fragile
    // }
 
    // CORRECT: confirm only touches Order; Customer updated via domain event (see Example 25)
    public void confirm(OrderId orderId) {
        Order order = orderRepo.findById(orderId) // => loads one aggregate
            .orElseThrow(() -> new IllegalArgumentException("Order not found: " + orderId));
        order.confirm();          // => domain logic on one aggregate
        orderRepo.save(order);    // => one save; one transaction boundary
        // => OrderConfirmed event collected inside order; published after save (Example 25)
    }
}

class ConfirmOrderService(                                            // => class ConfirmOrderService
    private val orderRepo: OrderRepository,    // => Order aggregate repository
    private val customerRepo: CustomerRepository // => Customer aggregate repository — separate
) {                                                                   // => expression
    fun confirm(orderId: OrderId) {                                   // => confirm method
        // => One transaction touches one aggregate only
        val order = orderRepo.findById(orderId) ?: throw IllegalArgumentException("Not found: $orderId") // => order initialised
        order.confirm()        // => domain logic; event collected inside
        orderRepo.save(order)  // => persist; transaction commits here
        // => CustomerRepository not touched in this transaction; Customer updated via event
    }
}

public class ConfirmOrderService                                      // => class ConfirmOrderService
// => Application Service: orchestrates one use case per public method
{
    private readonly IOrderRepository    _orderRepo;                  // => orderRepo field
    // => Interface dependency: domain code never imports EF Core or SQL directly
    private readonly ICustomerRepository _customerRepo; // => separate aggregate; NOT used here
    // => Injected to illustrate that Customer is NOT touched in this transaction
 
    public ConfirmOrderService(IOrderRepository orders, ICustomerRepository customers) // => ConfirmOrderService method
    // => Constructor injection: dependencies provided at registration time
    {
        _orderRepo    = orders;                                       // => _orderRepo assigned
        // => Stored; used in Confirm() to load and save the Order
        _customerRepo = customers; // => injected but not used in this transaction
        // => Stored; used by other methods that need customer access
    }
 
    public void Confirm(OrderId orderId)                              // => Confirm method
    // => Confirm use case: load Order, call domain method, persist; one aggregate, one TX
    {
        // => One transaction = one aggregate: only Order touched here
        var order = _orderRepo.FindById(orderId)                      // => order initialised
            ?? throw new KeyNotFoundException($"Order not found: {orderId}"); // => throws if guard fails
        // => FindById returns null if not found; null-coalescing throw makes that explicit
        order.Confirm();         // => domain logic inside aggregate
        // => Aggregate validates status and collects domain events; no persistence yet
        _orderRepo.Save(order);  // => persist; transaction boundary ends here
        // => DB commit happens at Save(); if Confirm() threw, we never reach this line
        // => Customer consistency achieved via OrderConfirmed event; not here
    }
}

import java.util.Optional;                                            // => namespace/package import
 
// Repository interface lives in the domain layer — no infrastructure imports
// => Domain layer depends on abstraction; infrastructure implements it
public interface OrderRepository {                                    // => OrderRepository field
    Optional<Order> findById(OrderId id); // => Optional: communicates "may not exist"
    void save(Order order);               // => upsert semantics: insert or update
    void delete(OrderId id);              // => remove from collection
    // => No SQL, no JPA, no database — pure domain concepts
}
 
// Infrastructure implementation — lives in the infra layer
// (Shown here for illustration; in production, this is in a separate package/module)
public class InMemoryOrderRepository implements OrderRepository {     // => OrderRepository field
    private final java.util.Map<OrderId, Order> store = new java.util.HashMap<>(); // => method declaration
    // => HashMap simulates a database for tests; real impl uses JPA/JDBC
 
    @Override public Optional<Order> findById(OrderId id) {           // => expression
        return Optional.ofNullable(store.get(id)); // => null → empty Optional
    }
    @Override public void save(Order order) {                         // => expression
        store.put(order.getId(), order); // => insert or overwrite
    }
    @Override public void delete(OrderId id) {                        // => expression
        store.remove(id); // => remove entry
    }
}
 
// Domain service depends only on the interface — testable without a database
OrderRepository repo = new InMemoryOrderRepository(); // => inject in production
Order o = new Order(OrderId.generate(), new Address(new Street("1 Main"), new City("NYC"), PostalCode.of("10001"))); // => OrderId.generate() called
repo.save(o);                                     // => stored
Optional<Order> found = repo.findById(o.getId()); // => found.isPresent() = true

import java.util.Optional                                             // => namespace/package import
 
// Interface in domain layer: no database imports allowed here
interface OrderRepository {                                           // => interface OrderRepository
    fun findById(id: OrderId): Order?       // => nullable return: idiomatic Kotlin optional
    fun save(order: Order)                  // => upsert
    fun delete(id: OrderId)                 // => remove
}
 
// In-memory implementation for tests and development
class InMemoryOrderRepository : OrderRepository {                     // => class InMemoryOrderRepository
    private val store = mutableMapOf<OrderId, Order>() // => mutable map simulates persistence
 
    override fun findById(id: OrderId) = store[id]    // => null if not found
    override fun save(order: Order) { store[order.id] = order } // => upsert
    override fun delete(id: OrderId) { store.remove(id) }      // => remove
}
 
val repo: OrderRepository = InMemoryOrderRepository() // => inject; swap for JPA impl in prod

// Interface in domain layer: only domain types; no EF, no IQueryable
public interface IOrderRepository                                     // => interface IOrderRepository
// => begins block
{
    Order? FindById(OrderId id);   // => nullable: communicates "may not exist"
    void Save(Order order);         // => upsert semantics
    void Delete(OrderId id);        // => remove
}
 
// In-memory implementation for tests
public sealed class InMemoryOrderRepository : IOrderRepository        // => class InMemoryOrderRepository
{
    private readonly Dictionary<OrderId, Order> _store = new();       // => Dictionary method
    // => Dictionary simulates a database; real impl uses EF Core
 
    public Order?  FindById(OrderId id)     => _store.GetValueOrDefault(id); // => null if missing
    public void    Save(Order order)         => _store[order.Id] = order;    // => insert or overwrite
    public void    Delete(OrderId id)        => _store.Remove(id);           // => remove entry
}
 
IOrderRepository repo = new InMemoryOrderRepository(); // => inject at composition root