Best Practices

public boolean check(Money w, Money n) {
// => Abbreviated method and parameter names
// => Method name "check" doesn't explain purpose
// => Parameters w/n cryptic - what do they represent?
    return w.compareTo(n) >= 0;
// => Logic unclear without context
// => What are we checking? Why >= 0?
}
// => Clever: short code, hard to understand
// => Saves typing but costs comprehension

public boolean isEligibleForProcessing(Money wealth, Money threshold) {
// => Descriptive method name documents purpose
// => "isEligibleForProcessing" explains business logic
// => Parameters named after domain concepts (wealth, threshold)
    return wealth.isGreaterThanOrEqualTo(threshold);
// => Fluent API method reads like natural language
// => Business rule self-documenting: wealth >= threshold
// => No comments needed - code tells the story
}
// => Clear: explicit names, readable logic
// => Takes more space but saves understanding time

public class PaymentService {
// => Class mixing calculation and persistence
// => Violates Single Responsibility Principle
    public Money processAndSave(Money amount) {
// => Method name with "And" indicates multiple responsibilities
// => Warning sign: method doing too much
        Money fee = amount.multiply(new BigDecimal("0.025"));
// => Business logic: calculate 2.5% fee
        // Database code mixed with calculation
        saveToDatabase(fee);
// => Persistence logic in same method
// => Tight coupling: can't calculate without DB
// => Hard to test: needs database for unit tests
        return fee;
// => Returns calculation result after saving
    }
}
// => Problem: two reasons to change (fee formula OR persistence)
// => Testing requires database mock
// => Can't reuse calculation logic independently

public class FeeCalculator {
// => Single responsibility: fee calculation only
// => Pure business logic, no side effects
    public Money calculateFee(Money amount) {
// => Focused method: one clear purpose
        return amount.multiply(new BigDecimal("0.025"));
// => Fee calculation logic isolated
// => Easy to test: no dependencies
// => Reusable across different contexts
    }
}
// => Benefits: testable without mocks, reusable, focused

public class PaymentRepository {
// => Single responsibility: persistence only
// => Infrastructure concern separated from business logic
    public void savePaymentRecord(PaymentRecord record) {
        // Persistence logic only
// => Database operations isolated here
// => Can swap persistence implementation without affecting calculation
// => Testable with in-memory or mock repository
    }
}
// => Benefits: separation of concerns, testability, flexibility
// => Compose these classes to achieve "processAndSave" behavior

public Contract createContract(Money price, String customerId) {
// => No validation: accepts any input
// => Null price crashes later in calculation logic
// => Negative price creates invalid business state
    return new Contract(price, customerId); // What if price is null or negative?
// => Problem propagates: invalid contract created
// => Debugging difficult: error far from source
// => No indication of what went wrong
}
// => Fails late: errors surface downstream
// => Debugging nightmare: root cause unclear

public Contract createContract(Money price, String customerId) {
// => Validation at entry point (fail fast)
    if (price == null || price.isNegative()) {
// => Guard clause: check price validity first
// => Null check prevents NullPointerException
// => isNegative() enforces business rule
        throw new IllegalArgumentException("Price must be a positive amount");
// => Explicit exception with actionable message
// => Caller knows exactly what went wrong
// => IllegalArgumentException: standard for bad input
    }
    if (customerId == null || customerId.isBlank()) {
// => Second guard clause: validate customer ID
// => isBlank() catches null, empty, whitespace-only
        throw new IllegalArgumentException("Customer ID is required");
// => Clear message: identifies missing field
// => Early detection before Contract construction
    }

    return new Contract(price, customerId);
// => Only reached with valid inputs
// => Contract constructor can trust parameters
// => No defensive code needed inside Contract
}
// => Benefits: errors detected immediately, clear messages
// => Debugging easy: stack trace points to source
// => System state remains consistent (no invalid contracts)

public class Money {
// => Mutable value object (anti-pattern)
    private BigDecimal amount;
// => Mutable field: can be changed after construction
    private Currency currency;
// => Both fields modifiable

    public void setAmount(BigDecimal amount) {
// => Setter allows mutation
        this.amount = amount; // Dangerous mutation
// => Changes object state after creation
// => Problems: thread safety, aliasing bugs
// => Multiple references see different values
    }
}
// => Risks: race conditions, unexpected behavior
// => Thread-unsafe: needs synchronization
// => Aliasing bugs: shared references modified

public final class Money {
// => final class: cannot be extended (immutability contract protected)
    private final BigDecimal amount;
// => final field: assigned once in constructor, never changes
    private final Currency currency;
// => final field: immutable after construction

    public Money(BigDecimal amount, Currency currency) {
// => Constructor: only place fields are set
        this.amount = amount;
// => Assign amount once
        this.currency = currency;
// => Assign currency once
// => No setters: fields never change after this
    }

    public Money add(Money other) {
// => Operation returns NEW Money instance
// => Doesn't modify current object
        validateSameCurrency(other);
// => Guard: validate before calculation
        return new Money(this.amount.add(other.amount), this.currency);
// => Create new Money with sum
// => Original Money unchanged
// => Functional approach: transform, don't mutate
    }

    // Getters only, no setters
// => Read-only access to fields
    public BigDecimal getAmount() {
        return amount;
// => Safe to return BigDecimal (also immutable)
    }
}
// => Benefits: thread-safe, no defensive copies needed
// => Can be safely shared across threads
// => No synchronization required

public abstract class Product { }
// => Base abstract class (inheritance root)
public abstract class PricedProduct extends Product { }
// => Intermediate abstraction: all products with prices
// => Problem: rigid hierarchy (Standard/Premium must extend this)
public class StandardProduct extends PricedProduct { }
// => Concrete standard product (inherits hierarchy)
public class PremiumProduct extends PricedProduct { }
// => Concrete premium product (inherits hierarchy)
// => Issues: tight coupling, inflexible, hard to change behavior
// => What if product needs different pricing at runtime?

public interface PricingStrategy {
// => Strategy pattern: define pricing behavior interface
    Money calculatePrice(Money basePrice);
// => Contract: all strategies implement this method
}

public class StandardPricing implements PricingStrategy {
// => Concrete strategy: standard pricing (no markup)
    public Money calculatePrice(Money basePrice) {
        return basePrice;
// => No transformation: return base price as-is
    }
}

public class PremiumPricing implements PricingStrategy {
// => Concrete strategy: premium pricing (with multiplier)
    private final BigDecimal multiplier;
// => Immutable multiplier (e.g., 1.5 for 50% markup)

    public PremiumPricing(BigDecimal multiplier) {
// => Constructor: configure strategy behavior
        this.multiplier = multiplier;
// => Set markup multiplier (1.2, 1.5, etc.)
    }

    public Money calculatePrice(Money basePrice) {
// => Apply premium pricing calculation
        return basePrice.multiply(multiplier);
// => Multiply base price by configured multiplier
// => Returns new Money (immutable)
    }
}

public class Product {
// => Product uses composition: HAS-A pricing strategy
    private final PricingStrategy pricingStrategy;
// => Composed strategy (dependency injection)
// => Can swap strategy at runtime (flexible)

    public Product(PricingStrategy pricingStrategy) {
// => Constructor injection: configure behavior
        this.pricingStrategy = pricingStrategy;
// => Accepts any PricingStrategy implementation
    }

    public Money getPrice(Money basePrice) {
// => Delegate pricing calculation to strategy
        return pricingStrategy.calculatePrice(basePrice);
// => Composition: Product doesn't know HOW to price
// => Strategy encapsulates pricing logic
    }
}
// => Benefits: flexible, testable, runtime behavior changes
// => Open/Closed: add new strategies without modifying Product

public Contract generate(Request request) {
// => Long method: 20+ lines doing multiple things
    if (request == null) throw new IllegalArgumentException("Request cannot be null");
// => Validation logic mixed with business logic
    if (request.getPrice().isNegativeOrZero()) throw new IllegalArgumentException("Price must be positive");
// => More validation (should be extracted)

    Money total = request.getPrice().add(request.getFee()).add(request.getTax());
// => Calculation logic (different responsibility)

    List<Payment> payments = new ArrayList<>();
// => Schedule generation logic starts here
    Money installment = total.divide(
// => Calculate per-installment amount
        BigDecimal.valueOf(request.getTermMonths()),
// => Divide total by term length
        RoundingMode.HALF_UP
// => Rounding strategy for division
    );
    LocalDate paymentDate = LocalDate.now();
// => Start date for schedule

    for (int i = 0; i < request.getTermMonths(); i++) {
// => Generate payment schedule (loop logic)
        paymentDate = paymentDate.plusMonths(1);
// => Increment date by one month
        payments.add(new Payment(installment, paymentDate));
// => Create and add payment
    }

    return new Contract(total, new Schedule(payments), request.getCustomerId());
// => Final construction (assembly logic)
}
// => Problems: hard to test, understand, modify
// => Multiple responsibilities in one method

public Contract generate(Request request) {
// => Main method: orchestrates workflow (6 lines)
// => Clear sequence of steps at high level
    validateRequest(request);
// => Step 1: Validate inputs (extracted)
    Money totalCost = calculateTotalCost(request);
// => Step 2: Calculate total (extracted)
    PaymentSchedule schedule = generatePaymentSchedule(request, totalCost);
// => Step 3: Generate schedule (extracted)

    return new Contract(totalCost, schedule, request.getCustomerId());
// => Step 4: Assemble result
}
// => Benefits: readable, testable steps, single responsibility

private void validateRequest(Request request) {
// => Extracted validation: one clear purpose
    if (request == null) {
// => Null check first
        throw new IllegalArgumentException("Request cannot be null");
    }
    if (request.getPrice().isNegativeOrZero()) {
// => Business rule validation
        throw new IllegalArgumentException("Price must be positive");
    }
}
// => Testable in isolation: unit test validation logic alone

private Money calculateTotalCost(Request request) {
// => Extracted calculation: clear name, focused logic
    return request.getPrice()
        .add(request.getFee())
// => Add fee to price
        .add(request.getTax());
// => Add tax to result
// => Fluent chaining: readable calculation
}
// => Pure function: no side effects, easy to test

private PaymentSchedule generatePaymentSchedule(Request request, Money totalCost) {
// => Extracted schedule generation: delegates to generator
    return scheduleGenerator.generate(
// => Composition: use dedicated schedule generator
        totalCost,
// => Total amount to divide into payments
        request.getTermMonths(),
// => Number of payment installments
        request.getPaymentFrequency()
// => Frequency: monthly, quarterly, etc.
    );
}
// => Delegation: schedule logic encapsulated elsewhere
// => Benefits: reusable, testable, focused methods

public class Calculator {
// => Generic name: Calculator for what?
    private static final BigDecimal RATE = new BigDecimal("0.025");
// => RATE: what kind of rate? Interest? Fee? Tax?

    public Money calc(Money w, int d) {
// => Abbreviated names: w (wealth?), d (days?), calc (calculate what?)
        if (d < 365) {
// => Magic number 365: why this threshold?
            throw new IllegalArgumentException("Invalid days");
// => Vague message: why invalid? What's the rule?
        }
        return w.multiply(RATE);
// => Logic unclear: multiplying by rate for what purpose?
    }
}
// => Problems: purpose unclear, hard to understand context

public class AnnualFeeCalculator {
// => Specific name: clearly calculates annual fees
    private static final BigDecimal ANNUAL_FEE_RATE = new BigDecimal("0.025");
// => Explicit constant: ANNUAL_FEE_RATE (2.5% annual fee)
// => Self-documenting: reader knows this is for annual fees

    public Money calculateAnnualFee(Money balance, int daysHeld) {
// => Descriptive method name: calculateAnnualFee (clear purpose)
// => Parameters named after domain concepts: balance, daysHeld
        if (daysHeld < 365) {
// => 365 in context: days in year (still could be constant)
            throw new IllegalArgumentException(
                "Balance must be held for at least 365 days"
// => Explicit error message: explains business rule
// => User understands WHY validation failed
            );
        }
        return balance.multiply(ANNUAL_FEE_RATE);
// => Clear calculation: balance × annual fee rate
// => Self-documenting code: no comments needed
    }
}
// => Benefits: purpose clear, easy to understand and maintain

public Duration calculateDuration(Frequency frequency, int count) {
// => Calculate duration based on frequency and count
    Duration duration;
// => Mutable variable: reassigned in each branch
    if (frequency == Frequency.DAILY) {
// => First condition check
        duration = Duration.ofDays(count);
// => Daily: count days directly
    } else if (frequency == Frequency.WEEKLY) {
        duration = Duration.ofWeeks(count);
// => Weekly: count weeks
    } else if (frequency == Frequency.MONTHLY) {
        duration = Duration.ofDays(count * 30);
// => Monthly: approximate 30 days per month
    } else if (frequency == Frequency.QUARTERLY) {
        duration = Duration.ofDays(count * 90);
// => Quarterly: 90 days (3 months)
    } else if (frequency == Frequency.ANNUALLY) {
        duration = Duration.ofDays(count * 365);
// => Annually: 365 days per year
    } else {
        throw new IllegalArgumentException("Unknown frequency: " + frequency);
// => Fallback: throw exception for unknown frequency
    }
    return duration;
// => Return computed duration
}
// => Problems: verbose, mutable variable, easy to miss case

public Duration calculateDuration(Frequency frequency, int count) {
// => Modern switch expression (Java 14+)
    return switch (frequency) {
// => Switch expression returns value directly (no mutation)
// => Exhaustiveness checked by compiler (all enum cases required)
        case DAILY -> Duration.ofDays(count);
// => Arrow syntax: concise, no break needed
// => Directly maps DAILY to days calculation
        case WEEKLY -> Duration.ofWeeks(count);
// => Each case is independent expression
        case MONTHLY -> Duration.ofDays(count * 30);
// => Approximate 30 days per month
        case QUARTERLY -> Duration.ofDays(count * 90);
// => 90 days for quarter (3 months)
        case ANNUALLY -> Duration.ofDays(count * 365);
// => 365 days per year
    };
// => No default needed: enum exhaustiveness enforced
// => Compiler error if new frequency added without case
}
// => Benefits: concise, safe (no forgotten cases), immutable

public class Money {
// => Traditional class: manual boilerplate (40+ lines)
    private final BigDecimal amount;
// => Immutable field
    private final Currency currency;
// => Immutable field

    public Money(BigDecimal amount, Currency currency) {
// => Constructor: manual field assignment
        this.amount = amount;
        this.currency = currency;
    }

    public BigDecimal getAmount() { return amount; }
// => Getter method (boilerplate)
    public Currency getCurrency() { return currency; }
// => Another getter method

    @Override
    public boolean equals(Object o) {
// => equals() method: 8 lines of boilerplate
        if (this == o) return true;
// => Reference equality check
        if (o == null || getClass() != o.getClass()) return false;
// => Type checking
        Money money = (Money) o;
// => Cast to compare fields
        return Objects.equals(amount, money.amount) &&
               Objects.equals(currency, money.currency);
// => Field-by-field comparison
    }

    @Override
    public int hashCode() {
// => hashCode() method: boilerplate
        return Objects.hash(amount, currency);
// => Hash based on fields
    }

    @Override
    public String toString() {
// => toString() method: formatting boilerplate
        return "Money{amount=" + amount + ", currency=" + currency + "}";
// => String representation
    }
}
// => Problem: 40+ lines for simple data carrier
// => Error-prone: easy to forget updating equals/hashCode

public record Money(BigDecimal amount, Currency currency) {
// => Record declaration: replaces 40+ lines with 1 line
// => Compiler auto-generates constructor, getters, equals, hashCode, toString
// => Immutable by default: all fields final
// => Accessor methods: amount(), currency() (not getAmount())

    // Can add custom validation
    public Money {
// => Compact constructor: no parameter list (auto-provided)
// => Runs before field initialization
        if (amount == null) {
// => Validation: check amount not null
            throw new IllegalArgumentException("Amount cannot be null");
// => Fail fast: validation at construction time
        }
        if (currency == null) {
// => Validation: check currency not null
            throw new IllegalArgumentException("Currency cannot be null");
        }
    }
// => Fields automatically assigned after validation passes
}
// => Benefits: 12 lines vs 40+, less error-prone, immutable
// => Compiler maintains equals/hashCode consistency

public User findUserById(String userId) {
// => Method may or may not find user
    // May return null
// => Return type doesn't indicate possibility of absence
    return database.query(userId);
// => Database query might return null
// => Caller must know to check (not enforced)
}

// Caller must remember to check
// => Easy to forget null check (runtime NPE risk)
User user = service.findUserById("123");
// => Might be null, but type doesn't indicate this
if (user != null) {
// => Manual null check required
// => Easily forgotten (no compiler help)
    processUser(user);
// => Only process if not null
}
// => Problem: absence not explicit, easy to forget check

public Optional<User> findUserById(String userId) {
// => Return type explicitly indicates possible absence
// => Optional<User>: compiler enforces handling
    return Optional.ofNullable(database.query(userId));
// => Wrap potentially null value in Optional
// => ofNullable: handles null gracefully (returns empty Optional)
}

// Explicit handling required
// => Functional approach: no null checks
service.findUserById("123")
// => Returns Optional<User>
    .ifPresent(this::processUser);
// => Only executes if User present
// => Method reference: clean syntax
// => No NPE risk: Optional handles absence

// Or with default
User user = service.findUserById("123")
// => Returns Optional<User>
    .orElse(User.guest());
// => Provide default value if absent
// => orElse: fallback to guest user
// => Always returns User (never null)

// Or throw exception
User user = service.findUserById("123")
// => Returns Optional<User>
    .orElseThrow(() -> new UserNotFoundException("123"));
// => Convert absence to exception
// => orElseThrow: explicit failure handling
// => Supplier lambda: create exception on demand

public Contract createContract(Request request) {
// => Anti-pattern: swallows exceptions and returns null
    try {
        validateRequest(request);
// => Validates request but exception handling below hides failures
        return repository.save(contract);
// => Database save operation with no error visibility
    } catch (Exception e) {
// => Catches ALL exceptions including RuntimeException
// => Silent failure: no logging, no rethrowing, no user feedback
        // Silent failure
    }
    return null;
// => Null return: caller cannot distinguish success from failure
// => Forces null checks throughout codebase
}

public class ContractService {
    private static final Logger logger = LoggerFactory.getLogger(ContractService.class);
// => SLF4J logger: abstraction over logging frameworks (Logback, Log4j2)
// => Static: one logger instance per class, minimal memory overhead

    public Contract createContract(Request request) {
        try {
            validateRequest(request);
// => Fail-fast validation: throws IllegalArgumentException on invalid input
            Contract contract = contractGenerator.generate(request);
// => Business logic: generates contract from validated request
            return repository.save(contract);
// => Persistence: may throw DataAccessException on database errors

        } catch (IllegalArgumentException e) {
// => Catches validation failures: specific exception type
            logger.warn("Invalid contract request: customerId={}, error={}",
                request.getCustomerId(), e.getMessage());
// => WARN level: expected error, not system failure
// => Structured logging: customerId for traceability, error message for details
            throw new ContractValidationException(
                "Cannot create contract: " + e.getMessage(), e);
// => Wraps in domain exception: exposes business error to caller
// => Preserves original exception: maintains stack trace for debugging

        } catch (DataAccessException e) {
// => Catches persistence failures: Spring's database exception hierarchy
            logger.error("Database error creating contract: customerId={}",
                request.getCustomerId(), e);
// => ERROR level: unexpected system failure requiring investigation
// => Context preservation: logs customer ID for incident correlation
            throw new ContractServiceException(
                "Failed to save contract. Please try again.", e);
// => User-friendly message: hides technical details, suggests retry
// => Wraps exception: converts infrastructure to business layer exception
        }
    }
}

public void writeReport(String filePath, List<Record> records) throws IOException {
// => Manual resource management: error-prone pattern
    BufferedWriter writer = null;
// => Initialize to null: allows finally block to check if resource opened
    try {
        writer = Files.newBufferedWriter(Paths.get(filePath));
// => Opens file: may throw IOException if path invalid or permissions insufficient
        writer.write("Report Header");
// => Writes data: may throw IOException on disk full or I/O errors
        // ... write records
    } finally {
// => Finally block: always executes, even if exception thrown
        if (writer != null) {
// => Null check required: resource may not have been created
            writer.close(); // May throw, hiding original exception
// => Close may throw IOException: suppresses original exception from try block
// => Resource leak risk: if close() throws, cleanup incomplete
        }
    }
}

public void writeReport(String filePath, List<Record> records) throws IOException {
// => Throws IOException: lets caller handle I/O failures
    try (BufferedWriter writer = Files.newBufferedWriter(
// => Try-with-resources: automatic close() call guaranteed
// => Resource declaration: BufferedWriter implements AutoCloseable
            Paths.get(filePath),
// => Path conversion: string to Path object for NIO operations
            StandardCharsets.UTF_8)) {
// => Explicit charset: prevents platform-dependent encoding issues
// => UTF-8: universal charset supporting all Unicode characters

        writer.write("Report - " + LocalDate.now());
// => Writes header with current date: ISO-8601 format (YYYY-MM-DD)
        writer.newLine();
// => Platform-independent line separator: \n (Unix) or \r\n (Windows)

        for (Record record : records) {
// => Enhanced for-loop: simple iteration over collection
            writer.write(record.toString());
// => Writes record data: uses Record's toString() implementation
            writer.newLine();
// => Each record on new line: human-readable format
        }

        // Writer automatically closed, even if exception occurs
// => Automatic cleanup: close() called when try block exits
// => Exception safety: if write fails, writer still closed properly
// => Suppressed exceptions: close() exceptions added to original exception
    }
}

public Distribution[] distributeAmount(Money total, Beneficiary[] beneficiaries) {
// => Array parameters: fixed size, no type safety for empty arrays
    if (beneficiaries.length == 0) {
// => Length field: arrays use field, not method like collections
        throw new IllegalArgumentException("Empty array");
// => Manual validation: no built-in isEmpty() method
    }

    Money perBeneficiary = total.divide(
// => Divides total equally among beneficiaries
        BigDecimal.valueOf(beneficiaries.length),
// => Converts int to BigDecimal: required for precise division
        RoundingMode.HALF_UP
// => Rounding mode: rounds 0.5 up (e.g., 2.5 → 3), financial standard
    );

    Distribution[] distributions = new Distribution[beneficiaries.length];
// => Fixed-size array: must know length at creation time
    for (int i = 0; i < beneficiaries.length; i++) {
// => Index-based loop: verbose, error-prone (off-by-one risks)
        distributions[i] = new Distribution(
// => Manual index assignment: must track index variable
            beneficiaries[i].getId(),
// => Array element access: bracket notation with index
            perBeneficiary
        );
    }
    return distributions;
// => Returns array: caller must handle fixed-size structure
}

public List<Distribution> distributeAmount(Money total, List<Beneficiary> beneficiaries) {
// => Collection parameter: dynamic size, rich API, type-safe generics
    if (beneficiaries.isEmpty()) {
// => isEmpty() method: clearer intent than size() == 0
        throw new IllegalArgumentException("Beneficiary list cannot be empty");
// => Descriptive message: explains business constraint
    }

    Money perBeneficiary = total.divide(
// => Divides total: calculates per-beneficiary amount
        BigDecimal.valueOf(beneficiaries.size()),
// => size() method: returns element count as int
        RoundingMode.HALF_UP
// => HALF_UP rounding: 0.5 rounds up, financial standard for fairness
    );

    return beneficiaries.stream()
// => Stream API: functional transformation pipeline
        .map(beneficiary -> new Distribution(
// => map operation: transforms each Beneficiary to Distribution
// => Lambda expression: concise function syntax
            beneficiary.getId(),
// => Extracts beneficiary ID: unique identifier for distribution
            perBeneficiary
// => Same amount per beneficiary: equal distribution calculated above
        ))
        .collect(Collectors.toList());
// => Terminal operation: collects stream elements into ArrayList
// => Returns List<Distribution>: collection with all distributions
}

public List<User> findEligibleUsers(List<User> allUsers, Money threshold) {
// => Filters users by balance threshold using anonymous class (verbose)
    return allUsers.stream()
// => Creates sequential stream from list for functional operations
        .filter(new Predicate<User>() {
// => Anonymous inner class: implements Predicate<User> functional interface
// => Verbose syntax: requires explicit type declaration and method signature
            @Override
// => Overrides abstract test() method from Predicate interface
            public boolean test(User user) {
// => test() method: receives User, returns boolean for filtering decision
                return user.getBalance().isGreaterThanOrEqualTo(threshold);
// => Business logic: checks if user balance meets minimum threshold
            }
        })
        .collect(Collectors.toList());
// => Terminal operation: collects filtered users into ArrayList
}

public List<User> findEligibleUsers(List<User> allUsers, Money threshold) {
// => Filters users using lambda expressions: concise functional style
    return allUsers.stream()
// => Stream creation: enables functional operations on collection
        .filter(user -> user.getBalance().isGreaterThanOrEqualTo(threshold))
// => Lambda filter: user -> boolean expression (no explicit Predicate type)
// => Arrow syntax: parameter -> body (single parameter, no parentheses needed)
        .filter(User::isActive)
// => Method reference: equivalent to user -> user.isActive()
// => Chained filter: combines multiple predicates for readability
        .collect(Collectors.toList());
// => Collects results: creates ArrayList with filtered users
}

public Money calculateTotalBalance(List<User> users) {
// => Calculates sum of all user balances using stream reduction
    return users.stream()
// => Stream over users: prepares for transformation and aggregation
        .map(User::getBalance)
// => Method reference: extracts balance from each user
// => Equivalent to: user -> user.getBalance()
// => Transforms Stream<User> to Stream<Money>
        .reduce(Money.ZERO, Money::add);
// => Terminal operation: combines all Money objects into single total
// => Money.ZERO: identity value (sum starts at 0)
// => Money::add: method reference to binary operator (sum accumulation)
// => Returns single Money: total of all user balances
}

public void notifyAllUsers(List<User> users, String message) {
// => Simple iteration with side effects: enhanced for-loop more readable than stream
    for (User user : users) {
// => Enhanced for-loop: iterates each User in collection
// => No index variable: cleaner than traditional for(int i=0; i<size; i++)
        notificationService.send(user.getEmail(), message);
// => Side effect: sends notification (external system interaction)
// => Email extraction: gets user email for notification delivery
// => No return value: forEach operation, not transformation
    }
}

public List<Payment> getOverduePayments(List<Payment> allPayments) {
// => Filters, sorts, and returns overdue unpaid payments using stream pipeline
    LocalDate today = LocalDate.now();
// => Current date: reference point for overdue calculation
// => LocalDate: date without time zone (ISO-8601 calendar)

    return allPayments.stream()
// => Stream pipeline: multiple intermediate operations before terminal collection
        .filter(payment -> payment.getDueDate().isBefore(today))
// => First filter: keeps payments with due date before today
// => Lambda predicate: payment -> boolean expression
        .filter(payment -> !payment.isPaid())
// => Second filter: excludes paid payments
// => Chained filters: each narrows result set (overdue AND unpaid)
        .sorted(Comparator.comparing(Payment::getDueDate))
// => Sorting: orders by due date ascending (oldest first)
// => Comparator.comparing(): creates comparator from key extractor
// => Payment::getDueDate: method reference extracting comparison key
        .collect(Collectors.toList());
// => Terminal operation: materializes stream into ArrayList
// => Returns List<Payment>: overdue unpaid payments sorted by due date
}

public Money calculateFee(User user, Money threshold) {
// => Nested conditionals: hard to follow, high cyclomatic complexity
    if (user != null) {
// => Null check: first validation but buried in nesting
        if (user.isActive()) {
// => Active check: second level nesting
            Money balance = user.getBalance();
// => Balance extraction: third level indentation
            if (balance.isGreaterThanOrEqualTo(threshold)) {
// => Threshold check: fourth level nesting
                if (user.hasDebt()) {
// => Debt check: fifth level nesting (arrow anti-pattern)
                    balance = balance.subtract(user.getDebt());
// => Mutates balance variable: reduces clarity
                    if (balance.isGreaterThanOrEqualTo(threshold)) {
// => Re-check threshold after debt subtraction: sixth level nesting
                        return balance.multiply(new BigDecimal("0.025"));
// => Fee calculation: 2.5% of balance after debt
                    } else {
                        return Money.ZERO;
// => Below threshold after debt: no fee
                    }
                } else {
                    return balance.multiply(new BigDecimal("0.025"));
// => No debt case: duplicate fee calculation logic
                }
            } else {
                return Money.ZERO;
// => Below threshold: no fee
            }
        } else {
            return Money.ZERO;
// => Inactive user: no fee
        }
    } else {
        throw new IllegalArgumentException("User cannot be null");
// => Null validation at bottom: should be at top
    }
}

public Money calculateFee(User user, Money threshold) {
// => Guard clauses: flat structure, early returns, clear happy path
    if (user == null) {
// => Guard clause 1: fail-fast null validation at top
        throw new IllegalArgumentException("User cannot be null");
// => Throws immediately: no nesting needed for remaining logic
    }

    if (!user.isActive()) {
// => Guard clause 2: early return for inactive users
        return Money.ZERO;
// => Exits early: remaining code only executes for active users
    }

    Money balance = user.getBalance();
// => Balance extraction: executed only for active users
    if (balance.isLessThan(threshold)) {
// => Guard clause 3: early return when balance below threshold
        return Money.ZERO;
// => No fee calculation needed: exits early
    }

    if (user.hasDebt()) {
// => Debt check: only executed if balance >= threshold
        balance = balance.subtract(user.getDebt());
// => Debt deduction: adjusts balance for fee calculation
        if (balance.isLessThan(threshold)) {
// => Re-check threshold: after debt subtraction
            return Money.ZERO;
// => Early return: no fee if balance drops below threshold
        }
    }

    return balance.multiply(new BigDecimal("0.025"));
// => Happy path at bottom: clear fee calculation (2.5%)
// => Single calculation: no duplication, all guards passed
}

public final class Money {
// => final class: cannot be subclassed (protects immutability contract)
    private final BigDecimal amount;
// => final field: assigned once in constructor, never changes
// => BigDecimal: immutable arbitrary-precision decimal (no floating-point errors)
    private final Currency currency;
// => final field: immutable currency (prevents currency mismatches)

    public Money(BigDecimal amount, Currency currency) {
// => Constructor: only way to set final fields
        if (amount == null) {
// => Null validation: prevents NullPointerException in operations
            throw new IllegalArgumentException("Amount cannot be null");
// => Fail-fast: rejects invalid state at construction time
        }
        if (currency == null) {
// => Currency validation: ensures all Money objects have valid currency
            throw new IllegalArgumentException("Currency cannot be null");
        }

        this.amount = amount;
// => Final field assignment: only allowed in constructor
        this.currency = currency;
// => One-time initialization: guarantees immutability
    }

    public Money add(Money other) {
// => Returns new Money: does not modify this object (immutability)
        validateSameCurrency(other);
// => Validation: prevents adding amounts with different currencies
        return new Money(this.amount.add(other.amount), this.currency);
// => Creates new instance: original objects unchanged
// => BigDecimal.add(): immutable operation, returns new BigDecimal
    }

    public Money multiply(BigDecimal multiplier) {
// => Multiplication: returns new Money, preserves original
        return new Money(this.amount.multiply(multiplier), this.currency);
// => New instance: currency preserved, amount scaled
// => BigDecimal.multiply(): precise multiplication without rounding errors
    }

    // Getters only, no setters
// => No setters: enforces immutability at API level
    public BigDecimal getAmount() {
// => Returns immutable BigDecimal: safe to expose
        return amount;
// => Direct return: BigDecimal itself immutable, no defensive copy needed
    }

    public Currency getCurrency() {
// => Currency enum/class: typically immutable in Java
        return currency;
// => Safe exposure: Currency instances are immutable
    }
}