121-java-object-oriented-design.mdc

---
author: Juan Antonio Breña Moral
version: 0.10.0-SNAPSHOT
---
# Java Object-Oriented Design Guidelines

## Role

You are a Senior software engineer with extensive experience in Java software development

## Goal

This document provides comprehensive guidelines for robust Java object-oriented design and refactoring. It emphasizes core principles like SOLID, DRY, and YAGNI, best practices for class and interface design including favoring composition over inheritance and designing for immutability.
The rules also cover mastering encapsulation, inheritance, and polymorphism, and finally, identifying and refactoring common object-oriented design code smells such as God Classes, Feature Envy, and Data Clumps to promote maintainable, flexible, and understandable code.

### Consultative Interaction Technique

This technique emphasizes **analyzing before acting** and **proposing options before implementing**. Instead of immediately making changes, the assistant:

1. **Analyzes** the current state and identifies specific issues
2. **Categorizes** problems by impact (CRITICAL, MAINTAINABILITY, etc.)
3. **Proposes** multiple solution options with clear trade-offs
4. **Asks** the user to choose their preferred approach
5. **Implements** based on user selection

**Benefits:**
- Builds user understanding of the codebase
- Ensures changes align with user preferences and constraints
- Teaches best practices through explanation
- Prevents unwanted modifications
- Encourages informed decision-making

**Example interaction:**
```
🔍 I found 3 Maven best practices improvements in this POM:

1. **CRITICAL: Hardcoded Dependency Versions**
- Problem: Dependencies have hardcoded versions scattered throughout the POM
- Solutions: A) Move to properties section B) Use dependencyManagement C) Import BOM files

2. **MAINTAINABILITY: Missing Plugin Version Management**
- Problem: Maven plugins lack explicit version declarations
- Solutions: A) Add pluginManagement section B) Define plugin versions in properties C) Use parent POM approach

3. **ORGANIZATION: Inconsistent POM Structure**
- Problem: Elements are not in logical order, affecting readability
- Solutions: A) Reorganize sections B) Add descriptive comments C) Use consistent naming conventions

Which would you like to implement? (1A, 1B, 1C, 2A, 2B, 2C, 3A, 3B, 3C, or 'show more details')
```

Focus on being consultative rather than prescriptive - analyze, propose, ask, then implement based on user choice.

### Implementing These Principles

These guidelines are built upon the following core principles:

1.  **Adherence to Fundamental Design Principles**: Embrace foundational principles like SOLID, DRY, and YAGNI. These principles are key to building systems that are robust, maintainable, flexible, and easy to understand.
2.  **Effective Class and Interface Design**: Employ best practices for designing classes and interfaces. This includes favoring composition over inheritance to achieve flexibility, programming to an interface rather than an implementation to promote loose coupling, keeping classes small and focused on a single responsibility, and designing for immutability where appropriate to enhance simplicity and thread-safety.
3.  **Mastery of Core OOP Concepts**: Thoroughly understand and correctly apply the pillars of object-oriented programming:
*   **Encapsulation**: Protect internal state and expose behavior through well-defined interfaces.
*   **Inheritance**: Model true "is-a" relationships, ensuring subclasses are substitutable for their base types (Liskov Substitution Principle).
*   **Polymorphism**: Allow objects of different types to respond to the same message in their own way, simplifying client code.
4.  **Proactive Code Smell Management**: Develop the ability to identify common object-oriented design "code smells" (e.g., God Class, Feature Envy, Data Clumps, Refused Bequest). Recognizing and refactoring these smells is crucial for improving the long-term health, maintainability, and clarity of the codebase.
5.  **Rigorous Safety and Validation**: NEVER apply any design recommendations without first ensuring the project compiles successfully. All refactoring must be validated through compilation checks and testing to prevent introducing regressions or breaking existing functionality.

## Constraints

Before applying any recommendations, ensure the project is in a valid state by running Maven compilation. Compilation failure is a BLOCKING condition that prevents any further processing.

- **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change
- **PREREQUISITE**: Project must compile successfully and pass basic validation checks before any optimization
- **CRITICAL SAFETY**: If compilation fails, IMMEDIATELY STOP and DO NOT CONTINUE with any recommendations
- **BLOCKING CONDITION**: Compilation errors must be resolved by the user before proceeding with any object-oriented design improvements
- **NO EXCEPTIONS**: Under no circumstances should design recommendations be applied to a project that fails to compile

## Examples

### Table of contents

- Example 1: Apply Fundamental Software Design Principles
- Example 2: Single Responsibility Principle (SRP)
- Example 3: Open/Closed Principle (OCP)
- Example 4: Liskov Substitution Principle (LSP)
- Example 5: Interface Segregation Principle (ISP)
- Example 6: Dependency Inversion Principle (DIP)
- Example 7: DRY (Don't Repeat Yourself)
- Example 8: YAGNI (You Ain't Gonna Need It)
- Example 9: Design Well-Structured and Maintainable Classes and Interfaces
- Example 10: Effectively Utilize Core Object-Oriented Concepts
- Example 11: Encapsulation
- Example 12: Inheritance
- Example 13: Polymorphism
- Example 14: Recognize and Address Common OOD Code Smells
- Example 15: Large Class / God Class
- Example 16: Feature Envy
- Example 17: Inappropriate Intimacy
- Example 18: Refused Bequest
- Example 19: Shotgun Surgery
- Example 20: Data Clumps
- Example 21: Creating and Destroying Objects
- Example 22: Consider Static Factory Methods Instead of Constructors
- Example 23: Consider a Builder When Faced with Many Constructor Parameters
- Example 24: Enforce the Singleton Property with a Private Constructor or an Enum Type
- Example 25: Prefer Dependency Injection to Hardwiring Resources
- Example 26: Avoid Creating Unnecessary Objects
- Example 27: Classes and Interfaces Best Practices
- Example 28: Minimize the Accessibility of Classes and Members
- Example 29: In Public Classes, Use Accessor Methods, Not Public Fields
- Example 30: Minimize Mutability
- Example 31: Favor Composition Over Inheritance
- Example 32: Design and Document for Inheritance or Else Prohibit It
- Example 33: Enums and Annotations
- Example 34: Use Enums Instead of Int Constants
- Example 35: Use Instance Fields Instead of Ordinals
- Example 36: Use EnumSet Instead of Bit Fields
- Example 37: Use EnumMap Instead of Ordinal Indexing
- Example 38: Consistently Use the Override Annotation
- Example 39: Method Design
- Example 40: Check Parameters for Validity
- Example 41: Make Defensive Copies When Needed
- Example 42: Design Method Signatures Carefully
- Example 43: Return Empty Collections or Arrays, Not Nulls
- Example 44: Return Optionals Judiciously
- Example 45: Exception Handling
- Example 46: Use Exceptions Only for Exceptional Conditions
- Example 47: Use Checked Exceptions for Recoverable Conditions and Runtime Exceptions for Programming Errors
- Example 48: Favor the Use of Standard Exceptions
- Example 49: Include Failure-Capture Information in Detail Messages
- Example 50: Don't Ignore Exceptions

### Example 1: Apply Fundamental Software Design Principles

Title: Apply Fundamental Software Design Principles
Description: Core principles like SOLID, DRY, and YAGNI are foundational to good object-oriented design, leading to more robust, maintainable, and understandable systems.

### Example 2: Single Responsibility Principle (SRP)

Title: A class should have one, and only one, reason to change.
Description: This means a class should only have one job or primary responsibility. If a class handles multiple responsibilities, changes to one responsibility might inadvertently affect others.

**Good example:**

```java
// Good: Separate responsibilities
class UserData {
    private String name;
    private String email;
    // constructor, getters
    public UserData(String name, String email) { this.name = name; this.email = email; }
    public String getName() { return name; }
    public String getEmail() { return email; }
}

class UserPersistence {
    public void saveUser(UserData user) {
        System.out.println("Saving user " + user.getName() + " to database.");
        // Database saving logic
    }
}

class UserEmailer {
    public void sendWelcomeEmail(UserData user) {
        System.out.println("Sending welcome email to " + user.getEmail());
        // Email sending logic
    }
}
```

**Bad example:**

```java
// Bad: User class with multiple responsibilities
class User {
    private String name;
    private String email;

    public User(String name, String email) { this.name = name; this.email = email; }

    public String getName() { return name; }
    public String getEmail() { return email; }

    public void saveToDatabase() {
        System.out.println("Saving user " + name + " to database.");
        // Database logic mixed in
    }

    public void sendWelcomeEmail() {
        System.out.println("Sending welcome email to " + email);
        // Email logic mixed in
    }
    // If email sending changes, or DB logic changes, this class needs to change.
}
```

### Example 3: Open/Closed Principle (OCP)

Title: Software entities should be open for extension but closed for modification.
Description: You should be able to add new functionality without changing existing, tested code. This is often achieved using interfaces, abstract classes, and polymorphism.

**Good example:**

```java
interface Shape {
    double calculateArea();
}

class Rectangle implements Shape {
    private double width, height;
    public Rectangle(double w, double h) { width=w; height=h; }
    @Override public double calculateArea() { return width * height; }
}

class Circle implements Shape {
    private double radius;
    public Circle(double r) { radius=r; }
    @Override public double calculateArea() { return Math.PI * radius * radius; }
}

// New shapes (e.g., Triangle) can be added by implementing Shape
// without modifying existing Shape, Rectangle, Circle, or AreaCalculator.
class AreaCalculator {
    public double getTotalArea(List<Shape> shapes) {
        return shapes.stream().mapToDouble(Shape::calculateArea).sum();
    }
}
```

**Bad example:**

```java
// Bad: AreaCalculator needs modification for new shapes
class AreaCalculatorBad {
    public double calculateRectangleArea(Rectangle rect) { return rect.width * rect.height; }
    public double calculateCircleArea(Circle circ) { return Math.PI * circ.radius * circ.radius; }
    // If a Triangle class is added, this class must be modified to add calculateTriangleArea().
}
class Rectangle { public double width, height; /* ... */ }
class Circle { public double radius; /* ... */ }
```

### Example 4: Liskov Substitution Principle (LSP)

Title: Subtypes must be substitutable for their base types.
Description: Objects of a superclass should be replaceable with objects of its subclasses without affecting the correctness of the program or causing unexpected behavior.

**Good example:**

```java
interface Bird {
    void move();
}

class FlyingBird implements Bird {
    public void fly() { System.out.println("Flying high!"); }
    @Override public void move() { fly(); }
}

class Sparrow extends FlyingBird { /* Can fly */ }

class Ostrich implements Bird { // Ostrich is a Bird but doesn't fly in the typical sense
    public void runFast() { System.out.println("Running fast on the ground!"); }
    @Override public void move() { runFast(); }
}

public class BirdLSPExample {
    public static void makeBirdMove(Bird bird) {
        bird.move(); // Works correctly for Sparrow (flies) and Ostrich (runs)
    }
    public static void main(String args) {
        makeBirdMove(new Sparrow());
        makeBirdMove(new Ostrich());
    }
}
```

**Bad example:**

```java
// Bad: Violating LSP
class Bird {
    public void fly() { System.out.println("Bird is flying."); }
}

class Penguin extends Bird {
    @Override
    public void fly() {
        // Penguins can't fly, so this method might do nothing or throw an exception.
        // This violates LSP because a Penguin can't simply replace a generic Bird where fly() is expected.
        throw new UnsupportedOperationException("Penguins can't fly.");
    }
    public void swim() { System.out.println("Penguin is swimming."); }
}

public class BirdLSPViolation {
    public static void letTheBirdFly(Bird bird) {
        bird.fly(); // This will crash if bird is a Penguin
    }
    public static void main(String args) {
        try {
            letTheBirdFly(new Penguin());
        } catch (UnsupportedOperationException e) {
            System.err.println(e.getMessage());
        }
    }
}
```

### Example 5: Interface Segregation Principle (ISP)

Title: Clients should not be forced to depend on interfaces they do not use.
Description: It's better to have many small, specific interfaces (role interfaces) than one large, general-purpose interface. This prevents classes from having to implement methods they don't need.

**Good example:**

```java
// Good: Segregated interfaces
interface Worker {
    void work();
}

interface Eater {
    void eat();
}

class HumanWorker implements Worker, Eater {
    @Override public void work() { System.out.println("Human working."); }
    @Override public void eat() { System.out.println("Human eating."); }
}

class RobotWorker implements Worker {
    @Override public void work() { System.out.println("Robot working efficiently."); }
    // RobotWorker does not need to implement eat()
}
```

**Bad example:**

```java
// Bad: Fat interface
interface IWorkerAndEater {
    void work();
    void eat(); // All implementers must provide eat(), even if they don't eat.
}

class Human implements IWorkerAndEater {
    @Override public void work() { /* ... */ }
    @Override public void eat() { /* ... */ }
}

class Robot implements IWorkerAndEater {
    @Override public void work() { System.out.println("Robot working."); }
    @Override public void eat() {
        // Robots don't eat. This method is forced and likely empty or throws exception.
        throw new UnsupportedOperationException("Robots don't eat.");
    }
}
```

### Example 6: Dependency Inversion Principle (DIP)

Title: High-level modules should not depend on low-level modules. Both should depend on abstractions.
Description: Abstractions (e.g., interfaces) should not depend on details. Details (concrete implementations) should depend on abstractions. This promotes loose coupling.

**Good example:**

```java
// Abstraction
interface MessageSender {
    void sendMessage(String message);
}

// Low-level module (detail)
class EmailSender implements MessageSender {
    @Override public void sendMessage(String message) { System.out.println("Email sent: " + message); }
}

// Low-level module (detail)
class SMSSender implements MessageSender {
    @Override public void sendMessage(String message) { System.out.println("SMS sent: " + message); }
}

// High-level module
class NotificationService {
    private final MessageSender sender; // Depends on abstraction

    public NotificationService(MessageSender sender) { // Dependency injected
        this.sender = sender;
    }

    public void notify(String message) {
        sender.sendMessage(message);
    }
}

public class DIPExample {
    public static void main(String args) {
        NotificationService emailNotifier = new NotificationService(new EmailSender());
        emailNotifier.notify("Hello via Email!");

        NotificationService smsNotifier = new NotificationService(new SMSSender());
        smsNotifier.notify("Hello via SMS!");
    }
}
```

**Bad example:**

```java
// Bad: High-level module depends directly on low-level module
class EmailerBad {
    public void sendEmail(String message) { System.out.println("Email sent: " + message); }
}

class NotificationServiceBad {
    private EmailerBad emailer; // Direct dependency on concrete EmailerBad

    public NotificationServiceBad() {
        this.emailer = new EmailerBad(); // Instantiates concrete class
    }

    public void sendNotification(String message) {
        emailer.sendEmail(message); // Tightly coupled
    }
    // If we want to use SMSSender, NotificationServiceBad needs to be changed.
}
```

### Example 7: DRY (Don't Repeat Yourself)

Title: Avoid duplication of code.
Description: Every piece of knowledge or logic must have a single, unambiguous, authoritative representation within a system. Use methods, classes, inheritance, or composition to centralize and reuse code.

**Good example:**

```java
class CalculationUtils {
    // Centralized validation logic
    public static void validatePositive(double value, String name) {
        if (value <= 0) {
            throw new IllegalArgumentException(name + " must be positive.");
        }
    }
}

class RectangleArea {
    public double calculate(double width, double height) {
        CalculationUtils.validatePositive(width, "Width");
        CalculationUtils.validatePositive(height, "Height");
        return width * height;
    }
}

class CircleVolume {
    public double calculate(double radius, double height) {
        CalculationUtils.validatePositive(radius, "Radius");
        CalculationUtils.validatePositive(height, "Height");
        return Math.PI * radius * radius * height;
    }
}
```

**Bad example:**

```java
// Bad: Duplicated validation logic
class RectangleAreaBad {
    public double calculate(double width, double height) {
        if (width <= 0) throw new IllegalArgumentException("Width must be positive."); // Duplicated
        if (height <= 0) throw new IllegalArgumentException("Height must be positive."); // Duplicated
        return width * height;
    }
}

class CircleVolumeBad {
    public double calculate(double radius, double height) {
        if (radius <= 0) throw new IllegalArgumentException("Radius must be positive."); // Duplicated
        if (height <= 0) throw new IllegalArgumentException("Height must be positive."); // Duplicated
        return Math.PI * radius * radius * height;
    }
}
```

### Example 8: YAGNI (You Ain't Gonna Need It)

Title: Implement features only when you actually need them.
Description: Avoid implementing functionality based on speculation that it might be needed in the future. This helps prevent over-engineering and keeps the codebase simpler and more focused on current requirements.

**Good example:**

```java
// Good: Simple class meeting current needs
class ReportGenerator {
    public String generateSimpleReport(List<String> data) {
        System.out.println("Generating simple report.");
        return "Report: " + String.join(", ", data);
    }
    // If PDF export is needed later, it can be added then.
    // No need to implement generatePdfReport, generateExcelReport etc. upfront.
}
```

**Bad example:**

```java
// Bad: Over-engineered with features not currently needed
class ReportGeneratorOverkill {
    public String generateHtmlReport(List<String> data) { /* ... */ return "html";}
    public byte[] generatePdfReport(List<String> data) {
        System.out.println("Generating PDF report (not actually used yet).");
        return new byte[0];
    }
    public byte[] generateExcelReport(List<String> data) {
        System.out.println("Generating Excel report (not actually used yet).");
        return new byte[0];
    }
    // Current requirement is only for HTML, but PDF and Excel are added "just in case".
}
```

### Example 9: Design Well-Structured and Maintainable Classes and Interfaces

Title: Design Well-Structured and Maintainable Classes and Interfaces
Description: Good class and interface design is crucial for building flexible and understandable OOD systems. Favor composition over inheritance, program to interfaces rather than implementations, keep classes small and focused, and design for immutability where appropriate. Use clear, descriptive naming conventions.

**Good example:**

```java
// Interface (Abstraction)
interface Engine {
    void start();
    void stop();
}

// Concrete Implementations
class PetrolEngine implements Engine {
    @Override public void start() { System.out.println("Petrol engine started."); }
    @Override public void stop() { System.out.println("Petrol engine stopped."); }
}

class ElectricEngine implements Engine {
    @Override public void start() { System.out.println("Electric engine silently started."); }
    @Override public void stop() { System.out.println("Electric engine silently stopped."); }
}

// Class using Composition and Programming to an Interface
class Car {
    private final Engine engine; // Depends on Engine interface (abstraction)
    private final String modelName;

    // Engine is injected (composition)
    public Car(String modelName, Engine engine) {
        this.modelName = modelName;
        this.engine = engine;
    }

    public void startCar() {
        System.out.print(modelName + ": ");
        engine.start();
    }

    public void stopCar() {
        System.out.print(modelName + ": ");
        engine.stop();
    }

    public String getModelName(){ return modelName; }
}

public class ClassDesignExample {
    public static void main(String args) {
        Car petrolCar = new Car("SedanX", new PetrolEngine());
        Car electricCar = new Car("EVMax", new ElectricEngine());

        petrolCar.startCar();
        electricCar.startCar();
        petrolCar.stopCar();
        electricCar.stopCar();
    }
}
```

**Bad example:**

```java
// Bad: Tight coupling, not programming to an interface
class BadCar {
    private final BadPetrolEngine engine; // Direct dependency on concrete BadPetrolEngine
    public BadCar() {
        this.engine = new BadPetrolEngine(); // Instantiates concrete class
    }
    public void start() { engine.startPetrol(); }
    // If we want an electric car, this class needs significant changes or a new similar class.
}
class BadPetrolEngine { public void startPetrol() { System.out.println("Bad petrol engine starts."); } }
```

### Example 10: Effectively Utilize Core Object-Oriented Concepts

Title: Effectively Utilize Core Object-Oriented Concepts
Description: Encapsulation, Inheritance, and Polymorphism are the three pillars of object-oriented programming.

### Example 11: Encapsulation

Title: Protect Internal State and Implementation Details
Description: Hide the internal state (fields) and implementation details of an object from the outside world. Expose a well-defined public interface (methods) for interacting with the object. Use access modifiers effectively to control visibility and protect invariants.

**Good example:**

```java
class BankAccount {
    private double balance; // Encapsulated: internal state is private
    private final String accountNumber;

    public BankAccount(String accountNumber, double initialBalance) {
        this.accountNumber = accountNumber;
        if (initialBalance < 0) throw new IllegalArgumentException("Initial balance cannot be negative.");
        this.balance = initialBalance;
    }

    // Public interface to interact with the balance
    public void deposit(double amount) {
        if (amount <= 0) throw new IllegalArgumentException("Deposit amount must be positive.");
        this.balance += amount;
        System.out.println("Deposited: " + amount + ", New Balance: " + this.balance);
    }

    public void withdraw(double amount) {
        if (amount <= 0) throw new IllegalArgumentException("Withdrawal amount must be positive.");
        if (amount > this.balance) throw new IllegalArgumentException("Insufficient funds.");
        this.balance -= amount;
        System.out.println("Withdrew: " + amount + ", New Balance: " + this.balance);
    }

    public double getBalance() { // Controlled access to balance
        return this.balance;
    }
    public String getAccountNumber() { return this.accountNumber; }
}
```

**Bad example:**

```java
// Bad: Poor encapsulation, exposing internal state
class UnsafeBankAccount {
    public double balance; // Public field: internal state exposed and can be freely modified
    public String accountNumber;

    public UnsafeBankAccount(String accNum, double initial) { this.accountNumber = accNum; this.balance = initial; }
    // No methods to control how balance is changed, invariants can be broken.
}
public class BadEncapsulationExample {
    public static void main(String args) {
        UnsafeBankAccount account = new UnsafeBankAccount("123", 100.0);
        account.balance = -500.0; // Direct modification, potentially breaking business rules
        System.out.println("Unsafe balance: " + account.balance);
    }
}
```

### Example 12: Inheritance

Title: Model "is-a" Relationships and Ensure LSP
Description: Use inheritance to model true "is-a" relationships, where a subclass is a more specific type of its superclass. Ensure that the Liskov Substitution Principle (LSP) is followed: subclasses must be substitutable for their base types without altering the correctness of the program.

**Good example:**

```java
abstract class Animal {
    private String name;
    public Animal(String name) { this.name = name; }
    public String getName() { return name; }
    public abstract void makeSound(); // Abstract method for polymorphism
}

class Dog extends Animal { // Dog IS-A Animal
    public Dog(String name) { super(name); }
    @Override public void makeSound() { System.out.println(getName() + " says: Woof!"); }
    public void fetch() { System.out.println(getName() + " is fetching."); }
}

class Cat extends Animal { // Cat IS-A Animal
    public Cat(String name) { super(name); }
    @Override public void makeSound() { System.out.println(getName() + " says: Meow!"); }
    public void purr() { System.out.println(getName() + " is purring."); }
}

public class InheritanceExample {
    public static void main(String args) {
        Animal myDog = new Dog("Buddy");
        Animal myCat = new Cat("Whiskers");
        myDog.makeSound();
        myCat.makeSound();
        // ((Dog)myDog).fetch(); // Can cast if sure of type to access specific methods
    }
}
```

**Bad example:**

```java
// Bad: Incorrect "is-a" relationship using composition instead
class Window {
    public void open() { System.out.println("Window opened."); }
    public void close() { System.out.println("Window closed."); }
}

class BetterCarDoor {
    private WindowComponent window = new WindowComponent();
    public void openDoor() { System.out.println("Car door opened."); }
    public void closeDoor() { System.out.println("Car door closed."); }
    public void openWindow() { window.open(); }
    public void closeWindow() { window.close(); }
    static class WindowComponent { /* Similar to Window */
        public void open() {System.out.println("Car window rolling down.");}
        public void close() {System.out.println("Car window rolling up.");}
    }
}
```

### Example 13: Polymorphism

Title: Enable Objects to Respond to the Same Message Differently
Description: Polymorphism allows objects of different classes (that share a common superclass or interface) to respond to the same message (method call) in their own specific ways. It simplifies client code, as it can interact with different types of objects through a common interface without needing to know their concrete types.

**Good example:**

```java
interface Drawable {
    void draw();
}

class CircleShape implements Drawable {
    @Override public void draw() { System.out.println("Drawing a Circle: O"); }
}

class SquareShape implements Drawable {
    @Override public void draw() { System.out.println("Drawing a Square: □"); }
}

class TriangleShape implements Drawable {
    @Override public void draw() { System.out.println("Drawing a Triangle: /\\"); }
}

public class PolymorphismExample {
    public static void drawShapes(List<Drawable> shapes) {
        for (Drawable shape : shapes) {
            shape.draw(); // Polymorphic call: actual method executed depends on shape's concrete type
        }
    }
    public static void main(String args) {
        List<Drawable> myShapes = List.of(
            new CircleShape(),
            new SquareShape(),
            new TriangleShape()
        );
        drawShapes(myShapes);
    }
}
```

**Bad example:**

```java
// Bad: Lacking polymorphism, using type checking and casting
class ShapeDrawer {
    public void drawSpecificShape(Object shape) {
        if (shape instanceof CircleShapeBad) {
            ((CircleShapeBad) shape).drawCircle();
        } else if (shape instanceof SquareShapeBad) {
            ((SquareShapeBad) shape).drawSquare();
        } else if (shape instanceof TriangleShapeBad) {
            ((TriangleShapeBad) shape).drawTriangle();
        } else {
            System.out.println("Unknown shape type.");
        }
        // This is not polymorphic. Adding new shapes requires modifying this method.
    }
}

class CircleShapeBad { public void drawCircle() { System.out.println("Drawing Circle (Bad)."); } }
class SquareShapeBad { public void drawSquare() { System.out.println("Drawing Square (Bad)."); } }
class TriangleShapeBad { public void drawTriangle() { System.out.println("Drawing Triangle (Bad)."); } }
```

### Example 14: Recognize and Address Common OOD Code Smells

Title: Recognize and Address Common OOD Code Smells
Description: Code smells are symptoms of potential underlying problems in the design. Recognizing and refactoring them can significantly improve code quality.

### Example 15: Large Class / God Class

Title: A class that knows or does too much.
Description: Such classes violate SRP and are hard to understand, maintain, and test. Consider breaking them down into smaller, more focused classes.

### Example 16: Feature Envy

Title: A method that seems more interested in a class other than the one it actually is in.
Description: This often means the method is using data from another class more than its own. Consider moving the method to the class it's "envious" of, or introduce a new class to mediate.

**Good example:**

```java
class Customer {
    private String name;
    private Address address;
    public Customer(String name, Address address) { this.name = name; this.address = address; }
    public String getFullAddressDetails() { // Method operates on its own Address object
        return address.getStreet() + ", " + address.getCity() + ", " + address.getZipCode();
    }
}
class Address {
    private String street, city, zipCode;
    public Address(String s, String c, String z) { street=s; city=c; zipCode=z; }
    public String getStreet() { return street; }
    public String getCity() { return city; }
    public String getZipCode() { return zipCode; }
}
```

**Bad example:**

```java
class Order {
    private double amount;
    private Customer customer; // Has a Customer
    public Order(double amount, Customer customer) { this.amount = amount; this.customer = customer; }

    // Bad: This method is more interested in Customer's Address than Order itself
    public String getCustomerShippingLabel() {
        Address addr = customer.getAddress(); // Assuming Customer has getAddress()
        return customer.getName() + "\n" + addr.getStreet() +
               "\n" + addr.getCity() + ", " + addr.getZipCode();
        // Better: Move this logic to Customer class as getShippingLabel() or similar.
    }
}
```

### Example 17: Inappropriate Intimacy

Title: Classes that spend too much time delving into each other's private parts.
Description: This indicates tight coupling and poor encapsulation. Classes should interact through well-defined public interfaces, not by accessing internal implementation details of others.

**Bad example:**

```java
class ServiceA {
    public int internalCounter = 0; // Public field, bad
    public void doSomething() { internalCounter++; }
}
class ServiceB {
    public void manipulateServiceA(ServiceA serviceA) {
        // Bad: Directly accessing and modifying internal state of ServiceA
        serviceA.internalCounter = 100;
        System.out.println("ServiceA counter directly set to: " + serviceA.internalCounter);
        // Better: ServiceA should have a method like resetCounter(int value) if this is valid behavior.
    }
}
```

### Example 18: Refused Bequest

Title: A subclass uses only some of the methods and properties inherited from its parents.
Description: This might indicate a violation of LSP or an incorrect inheritance hierarchy. The subclass might not truly be a substitutable type of the superclass.

### Example 19: Shotgun Surgery

Title: When a single conceptual change requires modifications in many different classes.
Description: This often indicates that a single responsibility has been spread too thinly across multiple classes, leading to high coupling and difficulty in making changes.

### Example 20: Data Clumps

Title: Bunches of data items that regularly appear together in multiple places.
Description: These data clumps often represent a missing concept that should be encapsulated into its own object or record.

**Good example:**

```java
// Good: Encapsulating related data into a Range object
record DateRange(LocalDate start, LocalDate end) {
    public DateRange {
        if (start.isAfter(end)) throw new IllegalArgumentException("Start date must be before end date.");
    }
}

class EventScheduler {
    public void scheduleEvent(String eventName, DateRange range) {
        System.out.println("Scheduling " + eventName + " from " + range.start() + " to " + range.end());
    }
    public boolean isDateInRange(LocalDate date, DateRange range) {
        return !date.isBefore(range.start()) && !date.isAfter(range.end());
    }
}
```

**Bad example:**

```java
// Bad: Data clump (startDay, startMonth, startYear, endDay, endMonth, endYear) passed around
class EventSchedulerBad {
    public void scheduleEvent(String eventName,
                              int startDay, int startMonth, int startYear,
                              int endDay, int endMonth, int endYear) {
        // ... logic using these separate date parts ...
        System.out.println("Scheduling event with many date parameters.");
    }
    public boolean checkOverlap(int sDay1, int sMon1, int sYr1, int eDay1, int eMon1, int eYr1,
                              int sDay2, int sMon2, int sYr2, int eDay2, int eMon2, int eYr2) {
        // ... complex logic with many parameters ...
        return false;
    }
    // This pattern of passing around many related date parts is a data clump.
}
```

### Example 21: Creating and Destroying Objects

Title: Best Practices for Object Creation and Destruction
Description: Effective object creation and destruction patterns improve code clarity, performance, and maintainability. These practices help avoid common pitfalls and leverage Java's capabilities effectively.

### Example 22: Consider Static Factory Methods Instead of Constructors

Title: Use static factory methods to provide more flexibility than constructors
Description: Static factory methods offer advantages like descriptive names, ability to return existing instances, and flexibility in return types.

**Good example:**

```java
public class BigInteger {
    // Static factory method with descriptive name
    public static BigInteger valueOf(long val) {
        if (val == 0) return ZERO;  // Return cached instance
        if (val > 0 && val <= MAX_CONSTANT) return posConst[(int) val];
        return new BigInteger(val);
    }

    // Private constructor
    private BigInteger(long val) { /* implementation */ }

    private static final BigInteger ZERO = new BigInteger(0);
    private static final BigInteger[] posConst = new BigInteger[MAX_CONSTANT + 1];
}

// Usage with clear intent
BigInteger zero = BigInteger.valueOf(0);  // Clear what we're creating
BigInteger hundred = BigInteger.valueOf(100);
```

**Bad example:**

```java
public class BigInteger {
    // Only constructor available - less flexible
    public BigInteger(long val) { /* implementation */ }

    // Client code is less clear
    BigInteger zero = new BigInteger(0);  // Not clear this could be cached
    BigInteger hundred = new BigInteger(100);  // Creates new instance every time
}
```

### Example 23: Consider a Builder When Faced with Many Constructor Parameters

Title: Use the Builder pattern for classes with multiple optional parameters
Description: The Builder pattern provides a readable alternative to telescoping constructors and is safer than JavaBeans pattern.

**Good example:**

```java
public class NutritionFacts {
    private final int servingSize;
    private final int servings;
    private final int calories;
    private final int fat;
    private final int sodium;
    private final int carbohydrate;

    public static class Builder {
        // Required parameters
        private final int servingSize;
        private final int servings;

        // Optional parameters - initialized to default values
        private int calories = 0;
        private int fat = 0;
        private int sodium = 0;
        private int carbohydrate = 0;

        public Builder(int servingSize, int servings) {
            this.servingSize = servingSize;
            this.servings = servings;
        }

        public Builder calories(int val) { calories = val; return this; }
        public Builder fat(int val) { fat = val; return this; }
        public Builder sodium(int val) { sodium = val; return this; }
        public Builder carbohydrate(int val) { carbohydrate = val; return this; }

        public NutritionFacts build() {
            return new NutritionFacts(this);
        }
    }

    private NutritionFacts(Builder builder) {
        servingSize = builder.servingSize;
        servings = builder.servings;
        calories = builder.calories;
        fat = builder.fat;
        sodium = builder.sodium;
        carbohydrate = builder.carbohydrate;
    }
}

// Usage - readable and flexible
NutritionFacts cocaCola = new NutritionFacts.Builder(240, 8)
    .calories(100)
    .sodium(35)
    .carbohydrate(27)
    .build();
```

**Bad example:**

```java
// Telescoping constructor pattern - hard to read and error-prone
public class NutritionFacts {
    private final int servingSize;
    private final int servings;
    private final int calories;
    private final int fat;
    private final int sodium;
    private final int carbohydrate;

    public NutritionFacts(int servingSize, int servings) {
        this(servingSize, servings, 0);
    }

    public NutritionFacts(int servingSize, int servings, int calories) {
        this(servingSize, servings, calories, 0);
    }

    public NutritionFacts(int servingSize, int servings, int calories, int fat) {
        this(servingSize, servings, calories, fat, 0);
    }

    public NutritionFacts(int servingSize, int servings, int calories, int fat, int sodium) {
        this(servingSize, servings, calories, fat, sodium, 0);
    }

    public NutritionFacts(int servingSize, int servings, int calories, int fat, int sodium, int carbohydrate) {
        this.servingSize = servingSize;
        this.servings = servings;
        this.calories = calories;
        this.fat = fat;
        this.sodium = sodium;
        this.carbohydrate = carbohydrate;
    }
}

// Usage - confusing parameter order, easy to make mistakes
NutritionFacts cocaCola = new NutritionFacts(240, 8, 100, 0, 35, 27);  // What do these numbers mean?
```

### Example 24: Enforce the Singleton Property with a Private Constructor or an Enum Type

Title: Use enum or private constructor with static field for singletons
Description: Enum-based singletons are the best way to implement singletons, providing serialization and reflection safety.

**Good example:**

```java
// Enum singleton - preferred approach
public enum DatabaseConnection {
    INSTANCE;

    public void connect() {
        System.out.println("Connecting to database...");
    }

    public void executeQuery(String query) {
        System.out.println("Executing: " + query);
    }
}

// Alternative: Static field with private constructor
public class Logger {
    private static final Logger INSTANCE = new Logger();

    private Logger() { /* private constructor */ }

    public static Logger getInstance() {
        return INSTANCE;
    }

    public void log(String message) {
        System.out.println("LOG: " + message);
    }
}

// Usage
DatabaseConnection.INSTANCE.connect();
Logger.getInstance().log("Application started");
```

**Bad example:**

```java
// Not thread-safe singleton
public class BadSingleton {
    private static BadSingleton instance;

    private BadSingleton() {}

    public static BadSingleton getInstance() {
        if (instance == null) {  // Race condition possible
            instance = new BadSingleton();
        }
        return instance;
    }
}
```

### Example 25: Prefer Dependency Injection to Hardwiring Resources

Title: Use dependency injection instead of hardcoded dependencies
Description: Classes should not create their dependencies directly but receive them from external sources, improving testability and flexibility.

**Good example:**

```java
public class SpellChecker {
    private final Lexicon dictionary;

    // Dependency injected through constructor
    public SpellChecker(Lexicon dictionary) {
        this.dictionary = Objects.requireNonNull(dictionary);
    }

    public boolean isValid(String word) {
        return dictionary.contains(word);
    }
}

interface Lexicon {
    boolean contains(String word);
}

class EnglishLexicon implements Lexicon {
    public boolean contains(String word) {
        // English dictionary lookup
        return true;
    }
}

// Usage - flexible and testable
Lexicon englishDict = new EnglishLexicon();
SpellChecker checker = new SpellChecker(englishDict);
```

**Bad example:**

```java
// Hardwired dependency - inflexible and hard to test
public class SpellChecker {
    private static final Lexicon dictionary = new EnglishLexicon();  // Hardcoded

    private SpellChecker() {}  // Noninstantiable

    public static boolean isValid(String word) {
        return dictionary.contains(word);
    }
}
```

### Example 26: Avoid Creating Unnecessary Objects

Title: Reuse objects when possible to improve performance
Description: Object creation can be expensive. Reuse immutable objects and avoid creating objects in loops when possible.

**Good example:**

```java
public class DateUtils {
    // Reuse expensive objects
    private static final DateTimeFormatter FORMATTER =
        DateTimeFormatter.ofPattern("yyyy-MM-dd");

    public String formatDate(LocalDate date) {
        return FORMATTER.format(date);  // Reuse formatter
    }

    // Use primitives when possible
    public boolean isEven(int number) {
        return number % 2 == 0;  // No object creation
    }
}
```

**Bad example:**

```java
public class DateUtils {
    public String formatDate(LocalDate date) {
        // Creates new formatter every time - expensive
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd");
        return formatter.format(date);
    }

    // Unnecessary autoboxing
    public boolean isEven(Integer number) {
        return number % 2 == 0;  // Creates Integer objects
    }
}
```

### Example 27: Classes and Interfaces Best Practices

Title: Design Classes and Interfaces for Maximum Effectiveness
Description: Well-designed classes and interfaces are the foundation of maintainable and robust Java applications. These practices ensure proper encapsulation, inheritance, and interface design.

### Example 28: Minimize the Accessibility of Classes and Members

Title: Use the most restrictive access level that makes sense
Description: Proper encapsulation hides implementation details and allows for easier maintenance and evolution of code.

**Good example:**

```java
public class BankAccount {
    private final String accountNumber;  // Private - implementation detail
    private double balance;              // Private - internal state

    // Package-private for testing
    static final double MINIMUM_BALANCE = 0.0;

    public BankAccount(String accountNumber, double initialBalance) {  // Public - part of API
        this.accountNumber = accountNumber;
        this.balance = initialBalance;
    }

    public double getBalance() {  // Public - part of API
        return balance;
    }

    public void deposit(double amount) {  // Public - part of API
        validateAmount(amount);
        balance += amount;
    }

    private void validateAmount(double amount) {  // Private - implementation detail
        if (amount <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
        }
    }
}
```

**Bad example:**

```java
public class BankAccount {
    public String accountNumber;  // Should be private
    public double balance;        // Should be private
    public static final double MINIMUM_BALANCE = 0.0;  // Unnecessarily public

    public BankAccount(String accountNumber, double initialBalance) {
        this.accountNumber = accountNumber;
        this.balance = initialBalance;
    }

    public void validateAmount(double amount) {  // Should be private
        if (amount <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
        }
    }
}
```

### Example 29: In Public Classes, Use Accessor Methods, Not Public Fields

Title: Provide getter and setter methods instead of exposing fields directly
Description: Accessor methods provide flexibility to add validation, logging, or other logic without breaking clients.

**Good example:**

```java
public class Point {
    private double x;
    private double y;

    public Point(double x, double y) {
        this.x = x;
        this.y = y;
    }

    public double getX() { return x; }
    public double getY() { return y; }

    public void setX(double x) {
        // Can add validation or other logic
        if (Double.isNaN(x)) {
            throw new IllegalArgumentException("x cannot be NaN");
        }
        this.x = x;
    }

    public void setY(double y) {
        if (Double.isNaN(y)) {
            throw new IllegalArgumentException("y cannot be NaN");
        }
        this.y = y;
    }
}
```

**Bad example:**

```java
public class Point {
    public double x;  // Direct field access - no validation possible
    public double y;  // Cannot add logic later without breaking clients

    public Point(double x, double y) {
        this.x = x;
        this.y = y;
    }
}
```

### Example 30: Minimize Mutability

Title: Make classes immutable when possible
Description: Immutable classes are simpler, safer, and can be freely shared. They are inherently thread-safe and have no temporal coupling.

**Good example:**

```java
public final class Complex {
    private final double real;
    private final double imaginary;

    public Complex(double real, double imaginary) {
        this.real = real;
        this.imaginary = imaginary;
    }

    public double realPart() { return real; }
    public double imaginaryPart() { return imaginary; }

    // Operations return new instances instead of modifying
    public Complex plus(Complex c) {
        return new Complex(real + c.real, imaginary + c.imaginary);
    }

    public Complex minus(Complex c) {
        return new Complex(real - c.real, imaginary - c.imaginary);
    }

    @Override
    public boolean equals(Object o) {
        if (o == this) return true;
        if (!(o instanceof Complex)) return false;
        Complex c = (Complex) o;
        return Double.compare(c.real, real) == 0 &&
               Double.compare(c.imaginary, imaginary) == 0;
    }

    @Override
    public int hashCode() {
        return Objects.hash(real, imaginary);
    }
}
```

**Bad example:**

```java
public class Complex {
    private double real;      // Mutable fields
    private double imaginary; // Mutable fields

    public Complex(double real, double imaginary) {
        this.real = real;
        this.imaginary = imaginary;
    }

    public double getRealPart() { return real; }
    public double getImaginaryPart() { return imaginary; }

    // Mutating operations - not thread-safe, harder to reason about
    public void plus(Complex c) {
        this.real += c.real;
        this.imaginary += c.imaginary;
    }

    public void setReal(double real) { this.real = real; }
    public void setImaginary(double imaginary) { this.imaginary = imaginary; }
}
```

### Example 31: Favor Composition Over Inheritance

Title: Use composition instead of inheritance when you want to reuse code
Description: Composition is more flexible than inheritance and avoids the fragility of inheritance hierarchies.

**Good example:**

```java
// Using composition
public class InstrumentedSet<E> {
    private final Set<E> s;
    private int addCount = 0;

    public InstrumentedSet(Set<E> s) {
        this.s = s;
    }

    public boolean add(E e) {
        addCount++;
        return s.add(e);
    }

    public boolean addAll(Collection<? extends E> c) {
        addCount += c.size();
        return s.addAll(c);
    }

    public int getAddCount() {
        return addCount;
    }

    // Delegate other methods to the wrapped set
    public int size() { return s.size(); }
    public boolean isEmpty() { return s.isEmpty(); }
    public boolean contains(Object o) { return s.contains(o); }
    // ... other delegating methods
}
```

**Bad example:**

```java
// Using inheritance - fragile and error-prone
public class InstrumentedHashSet<E> extends HashSet<E> {
    private int addCount = 0;

    @Override
    public boolean add(E e) {
        addCount++;
        return super.add(e);
    }

    @Override
    public boolean addAll(Collection<? extends E> c) {
        addCount += c.size();
        return super.addAll(c);  // This calls add() internally, double-counting!
    }

    public int getAddCount() {
        return addCount;
    }
}
```

### Example 32: Design and Document for Inheritance or Else Prohibit It

Title: Either design classes specifically for inheritance or make them final
Description: Classes not designed for inheritance can break when subclassed. Document self-use patterns or prohibit inheritance.

**Good example:**

```java
// Designed for inheritance with proper documentation
public abstract class AbstractProcessor {

    /**
     * Processes the given data. This implementation calls {@link #validate(String)}
     * followed by {@link #transform(String)}. Subclasses may override this method
     * to provide different processing logic.
     *
     * @param data the data to process
     * @return the processed result
     * @throws IllegalArgumentException if data is invalid
     */
    public String process(String data) {
        validate(data);
        return transform(data);
    }

    /**
     * Validates the input data. The default implementation checks for null.
     * Subclasses may override to provide additional validation.
     */
    protected void validate(String data) {
        if (data == null) {
            throw new IllegalArgumentException("Data cannot be null");
        }
    }

    /**
     * Transforms the validated data. Subclasses must implement this method.
     */
    protected abstract String transform(String data);
}

// Or prohibit inheritance
public final class UtilityClass {
    private UtilityClass() { /* prevent instantiation */ }

    public static String formatName(String firstName, String lastName) {
        return firstName + " " + lastName;
    }
}
```

**Bad example:**

```java
// Not designed for inheritance but not prohibited
public class DataProcessor {
    public String process(String data) {
        // Complex logic that might break if overridden
        String validated = validate(data);
        String transformed = transform(validated);
        return finalize(transformed);
    }

    private String validate(String data) { /* ... */ return data; }
    private String transform(String data) { /* ... */ return data; }
    private String finalize(String data) { /* ... */ return data; }
}
```

### Example 33: Enums and Annotations

Title: Effective Use of Enums and Annotations
Description: Enums and annotations are powerful Java features that, when used correctly, can make code more readable, type-safe, and maintainable.

### Example 34: Use Enums Instead of Int Constants

Title: Replace int constants with type-safe enums
Description: Enums provide type safety, namespace protection, and additional functionality that int constants cannot offer.

**Good example:**

```java
public enum Planet {
    MERCURY(3.302e+23, 2.439e6),
    VENUS  (4.869e+24, 6.052e6),
    EARTH  (5.975e+24, 6.378e6),
    MARS   (6.419e+23, 3.393e6);

    private final double mass;           // In kilograms
    private final double radius;         // In meters
    private final double surfaceGravity; // In m / s^2

    // Universal gravitational constant in m^3 / kg s^2
    private static final double G = 6.67300E-11;

    Planet(double mass, double radius) {
        this.mass = mass;
        this.radius = radius;
        surfaceGravity = G * mass / (radius * radius);
    }

    public double mass()           { return mass; }
    public double radius()         { return radius; }
    public double surfaceGravity() { return surfaceGravity; }

    public double surfaceWeight(double mass) {
        return mass * surfaceGravity;  // F = ma
    }
}

// Usage
double earthWeight = 175;
double mass = earthWeight / Planet.EARTH.surfaceGravity();
for (Planet p : Planet.values()) {
    System.out.printf("Weight on %s is %f%n", p, p.surfaceWeight(mass));
}
```

**Bad example:**

```java
// Int constants - not type-safe, no namespace
public class Planet {
    public static final int MERCURY = 0;
    public static final int VENUS   = 1;
    public static final int EARTH   = 2;
    public static final int MARS    = 3;

    // Separate arrays for data - error-prone
    private static final double[] MASS = {3.302e+23, 4.869e+24, 5.975e+24, 6.419e+23};
    private static final double[] RADIUS = {2.439e6, 6.052e6, 6.378e6, 3.393e6};

    public static double surfaceWeight(int planet, double mass) {
        // No compile-time checking - could pass any int
        if (planet < 0 || planet >= MASS.length) {
            throw new IllegalArgumentException("Invalid planet: " + planet);
        }
        // Complex calculations with array indexing
        return mass * (6.67300E-11 * MASS[planet] / (RADIUS[planet] * RADIUS[planet]));
    }
}
```

### Example 35: Use Instance Fields Instead of Ordinals

Title: Don't derive values from enum ordinals; use instance fields
Description: Ordinal values can change when enum constants are reordered, making code fragile.

**Good example:**

```java
public enum Ensemble {
    SOLO(1), DUET(2), TRIO(3), QUARTET(4), QUINTET(5),
    SEXTET(6), SEPTET(7), OCTET(8), DOUBLE_QUARTET(8),
    NONET(9), DECTET(10), TRIPLE_QUARTET(12);

    private final int numberOfMusicians;

    Ensemble(int size) {
        this.numberOfMusicians = size;
    }

    public int numberOfMusicians() {
        return numberOfMusicians;
    }
}
```

**Bad example:**

```java
public enum Ensemble {
    SOLO, DUET, TRIO, QUARTET, QUINTET,
    SEXTET, SEPTET, OCTET, NONET, DECTET;

    public int numberOfMusicians() {
        return ordinal() + 1;  // Fragile - breaks if order changes
    }
}
```

### Example 36: Use EnumSet Instead of Bit Fields

Title: Replace bit field enums with EnumSet for better type safety and performance
Description: EnumSet provides all the benefits of bit fields with better readability and type safety.

**Good example:**

```java
public class Text {
    public enum Style { BOLD, ITALIC, UNDERLINE, STRIKETHROUGH }

    // EnumSet - type-safe and efficient
    public void applyStyles(Set<Style> styles) {
        System.out.printf("Applying styles %s to text%n", styles);
        // Implementation here
    }
}

// Usage
text.applyStyles(EnumSet.of(Style.BOLD, Style.ITALIC));
```

**Bad example:**

```java
public class Text {
    public static final int STYLE_BOLD          = 1 << 0;  // 1
    public static final int STYLE_ITALIC        = 1 << 1;  // 2
    public static final int STYLE_UNDERLINE     = 1 << 2;  // 4
    public static final int STYLE_STRIKETHROUGH = 1 << 3;  // 8

    // Bit field - not type-safe
    public void applyStyles(int styles) {
        System.out.printf("Applying styles %s to text%n", styles);
        // Implementation here
    }
}

// Usage - error-prone, no type safety
text.applyStyles(STYLE_BOLD | STYLE_ITALIC);
```

### Example 37: Use EnumMap Instead of Ordinal Indexing

Title: Use EnumMap for enum-keyed data instead of ordinal indexing
Description: EnumMap is specifically designed for enum keys and provides better performance and type safety.

**Good example:**

```java
public enum Phase {
    SOLID, LIQUID, GAS;

    public enum Transition {
        MELT(SOLID, LIQUID), FREEZE(LIQUID, SOLID),
        BOIL(LIQUID, GAS), CONDENSE(GAS, LIQUID),
        SUBLIME(SOLID, GAS), DEPOSIT(GAS, SOLID);

        private final Phase from;
        private final Phase to;

        Transition(Phase from, Phase to) {
            this.from = from;
            this.to = to;
        }

        // Initialize the phase transition map
        private static final Map<Phase, Map<Phase, Transition>> m =
            Stream.of(values()).collect(groupingBy(t -> t.from,
                () -> new EnumMap<>(Phase.class),
                toMap(t -> t.to, t -> t, (x, y) -> y, () -> new EnumMap<>(Phase.class))));

        public static Transition from(Phase from, Phase to) {
            return m.get(from).get(to);
        }
    }
}
```

**Bad example:**

```java
public enum Phase {
    SOLID, LIQUID, GAS;

    public enum Transition {
        MELT, FREEZE, BOIL, CONDENSE, SUBLIME, DEPOSIT;

        // Ordinal-based array - fragile and error-prone
        private static final Transition[][] TRANSITIONS = {
            { null,    MELT,     SUBLIME  },  // SOLID
            { FREEZE,  null,     BOIL     },  // LIQUID
            { DEPOSIT, CONDENSE, null     }   // GAS
        };

        public static Transition from(Phase from, Phase to) {
            return TRANSITIONS[from.ordinal()][to.ordinal()];
        }
    }
}
```

### Example 38: Consistently Use the Override Annotation

Title: Always use @Override when overriding methods
Description: The @Override annotation catches errors at compile time and makes code more readable.

**Good example:**

```java
public class Bigram {
    private final char first;
    private final char second;

    public Bigram(char first, char second) {
        this.first = first;
        this.second = second;
    }

    @Override
    public boolean equals(Object o) {  // Correct signature
        if (!(o instanceof Bigram)) return false;
        Bigram b = (Bigram) o;
        return b.first == first && b.second == second;
    }

    @Override
    public int hashCode() {
        return 31 * first + second;
    }

    @Override
    public String toString() {
        return String.format("(%c, %c)", first, second);
    }
}
```

**Bad example:**

```java
public class Bigram {
    private final char first;
    private final char second;

    public Bigram(char first, char second) {
        this.first = first;
        this.second = second;
    }

    // Missing @Override - typo in method signature won't be caught
    public boolean equals(Bigram b) {  // Wrong signature! Should be equals(Object)
        return b.first == first && b.second == second;
    }

    public int hashCode() {  // Missing @Override
        return 31 * first + second;
    }
}
```

### Example 39: Method Design

Title: Design Methods for Clarity, Safety, and Usability
Description: Well-designed methods are the building blocks of maintainable code. These practices ensure methods are robust, clear, and easy to use correctly.

### Example 40: Check Parameters for Validity

Title: Validate method parameters early and clearly
Description: Fail fast by checking parameters at the beginning of methods. This makes debugging easier and prevents corruption of object state.

**Good example:**

```java
public class MathUtils {
    /**
     * Returns a BigInteger whose value is (this mod m).
     * @param m the modulus, which must be positive
     * @return this mod m
     * @throws ArithmeticException if m <= 0
     */
    public BigInteger mod(BigInteger m) {
        if (m.signum() <= 0) {
            throw new ArithmeticException("Modulus <= 0: " + m);
        }
        // ... do the computation
        return this;
    }

    /**
     * Returns the index of the first occurrence of needle in haystack,
     * or -1 if needle is not contained in haystack.
     * @param haystack the string to search in
     * @param needle the string to search for
     * @throws NullPointerException if haystack or needle is null
     */
    public static int indexOf(String haystack, String needle) {
        Objects.requireNonNull(haystack, "haystack");
        Objects.requireNonNull(needle, "needle");
        // ... do the search
        return haystack.indexOf(needle);
    }
}
```

**Bad example:**

```java
public class MathUtils {
    public BigInteger mod(BigInteger m) {
        // No parameter validation - could cause confusing errors later
        // ... do the computation
        return this;
    }

    public static int indexOf(String haystack, String needle) {
        // No null checks - will throw NullPointerException at some random point
        return haystack.indexOf(needle);
    }
}
```

### Example 41: Make Defensive Copies When Needed

Title: Protect against malicious or accidental modification of mutable parameters
Description: When accepting mutable objects as parameters or returning them, make defensive copies to maintain class invariants.

**Good example:**

```java
public final class Period {
    private final Date start;
    private final Date end;

    /**
     * @param start the beginning of the period
     * @param end the end of the period; must not precede start
     * @throws IllegalArgumentException if start is after end
     * @throws NullPointerException if start or end is null
     */
    public Period(Date start, Date end) {
        this.start = new Date(start.getTime());  // Defensive copy
        this.end = new Date(end.getTime());      // Defensive copy

        if (this.start.compareTo(this.end) > 0) {
            throw new IllegalArgumentException(this.start + " after " + this.end);
        }
    }

    public Date start() {
        return new Date(start.getTime());  // Defensive copy on return
    }

    public Date end() {
        return new Date(end.getTime());    // Defensive copy on return
    }
}
```

**Bad example:**

```java
public final class Period {
    private final Date start;
    private final Date end;

    public Period(Date start, Date end) {
        if (start.compareTo(end) > 0) {
            throw new IllegalArgumentException(start + " after " + end);
        }
        this.start = start;  // No defensive copy - client can modify after construction
        this.end = end;      // No defensive copy - client can modify after construction
    }

    public Date start() {
        return start;  // No defensive copy - client can modify internal state
    }

    public Date end() {
        return end;    // No defensive copy - client can modify internal state
    }
}
```

### Example 42: Design Method Signatures Carefully

Title: Choose method names carefully and avoid long parameter lists
Description: Good method signatures are self-documenting and hard to use incorrectly.

**Good example:**

```java
public class UserService {
    // Clear, descriptive method names
    public User createUser(String username, String email, LocalDate birthDate) {
        // Implementation
        return new User(username, email, birthDate);
    }

    // Use builder pattern for many parameters
    public static class UserBuilder {
        private String username;
        private String email;
        private LocalDate birthDate;
        private String firstName;
        private String lastName;
        private Address address;

        public UserBuilder username(String username) { this.username = username; return this; }
        public UserBuilder email(String email) { this.email = email; return this; }
        public UserBuilder birthDate(LocalDate birthDate) { this.birthDate = birthDate; return this; }
        public UserBuilder firstName(String firstName) { this.firstName = firstName; return this; }
        public UserBuilder lastName(String lastName) { this.lastName = lastName; return this; }
        public UserBuilder address(Address address) { this.address = address; return this; }

        public User build() {
            return new User(this);
        }
    }

    // Use helper classes to group related parameters
    public void updateUserProfile(User user, ProfileUpdate update) {
        // Implementation
    }
}

class ProfileUpdate {
    private final String firstName;
    private final String lastName;
    private final Address address;

    // Constructor and getters
}
```

**Bad example:**

```java
public class UserService {
    // Unclear method name and too many parameters
    public User doUserStuff(String s1, String s2, int d, int m, int y,
                           String s3, String s4, String s5, String s6, String s7) {
        // What do these parameters mean?
        return new User(s1, s2, LocalDate.of(y, m, d));
    }

    // Ambiguous parameter types
    public void updateUser(String username, String data) {
        // What kind of data? How is it formatted?
    }
}
```

### Example 43: Return Empty Collections or Arrays, Not Nulls

Title: Never return null from methods that return collections or arrays
Description: Returning null forces clients to handle null checks and is a common source of bugs.

**Good example:**

```java
public class ShoppingCart {
    private final List<Item> items = new ArrayList<>();

    /**
     * Returns a list of items in the cart.
     * @return the items in the cart (never null, but may be empty)
     */
    public List<Item> getItems() {
        return new ArrayList<>(items);  // Return copy of list, never null
    }

    /**
     * Returns items matching the given category.
     * @param category the category to filter by
     * @return matching items (never null, but may be empty)
     */
    public List<Item> getItemsByCategory(String category) {
        return items.stream()
                   .filter(item -> category.equals(item.getCategory()))
                   .collect(Collectors.toList());  // Returns empty list if no matches
    }

    /**
     * Returns an array of item names.
     * @return array of item names (never null, but may be empty)
     */
    public String[] getItemNames() {
        return items.stream()
                   .map(Item::getName)
                   .toArray(String[]::new);  // Returns empty array if no items
    }
}
```

**Bad example:**

```java
public class ShoppingCart {
    private final List<Item> items = new ArrayList<>();

    public List<Item> getItems() {
        return items.isEmpty() ? null : new ArrayList<>(items);  // Bad: returns null
    }

    public List<Item> getItemsByCategory(String category) {
        List<Item> result = items.stream()
                                .filter(item -> category.equals(item.getCategory()))
                                .collect(Collectors.toList());
        return result.isEmpty() ? null : result;  // Bad: returns null
    }

    public String[] getItemNames() {
        if (items.isEmpty()) {
            return null;  // Bad: returns null instead of empty array
        }
        return items.stream()
                   .map(Item::getName)
                   .toArray(String[]::new);
    }
}
```

### Example 44: Return Optionals Judiciously

Title: Use Optional for methods that may not return a value, but use it carefully
Description: Optional is intended for return types where there might legitimately be no result and the client needs to perform special processing.

**Good example:**

```java
public class UserRepository {
    private final Map<String, User> users = new HashMap<>();

    /**
     * Finds a user by username.
     * @param username the username to search for
     * @return an Optional containing the user if found, empty otherwise
     */
    public Optional<User> findByUsername(String username) {
        return Optional.ofNullable(users.get(username));
    }

    /**
     * Gets the maximum age among all users.
     * @return an Optional containing the max age if users exist, empty otherwise
     */
    public OptionalInt getMaxAge() {
        return users.values().stream()
                   .mapToInt(User::getAge)
                   .max();
    }
}

// Usage
Optional<User> user = repository.findByUsername("john");
if (user.isPresent()) {
    System.out.println("Found user: " + user.get().getName());
} else {
    System.out.println("User not found");
}

// Or with functional style
repository.findByUsername("john")
         .ifPresentOrElse(
             u -> System.out.println("Found: " + u.getName()),
             () -> System.out.println("User not found")
         );
```

**Bad example:**

```java
public class UserRepository {
    private final Map<String, User> users = new HashMap<>();

    // Bad: Using Optional for fields
    private Optional<String> defaultUsername = Optional.empty();

    // Bad: Using Optional for parameters
    public void updateUser(Optional<String> username, Optional<String> email) {
        // This makes the API harder to use
    }

    // Bad: Using Optional for collections
    public Optional<List<User>> getAllUsers() {
        return users.isEmpty() ? Optional.empty() : Optional.of(new ArrayList<>(users.values()));
        // Should just return empty list instead
    }

    // Bad: Optional in performance-critical code where null would be fine
    public Optional<User> findByUsernameInLoop(String username) {
        // If this is called in a tight loop, the Optional allocation overhead matters
        return Optional.ofNullable(users.get(username));
    }
}
```

### Example 45: Exception Handling

Title: Handle Exceptions Effectively and Appropriately
Description: Proper exception handling makes code more robust and easier to debug. These practices ensure exceptions are used correctly and provide meaningful information.

### Example 46: Use Exceptions Only for Exceptional Conditions

Title: Don't use exceptions for ordinary control flow
Description: Exceptions should be used for exceptional conditions, not for normal program flow. They are expensive and make code harder to understand.

**Good example:**

```java
public class NumberProcessor {
    public void processNumbers(int[] numbers) {
        for (int number : numbers) {  // Normal iteration
            if (isValid(number)) {    // Normal condition checking
                process(number);
            } else {
                System.out.println("Skipping invalid number: " + number);
            }
        }
    }

    private boolean isValid(int number) {
        return number >= 0 && number <= 1000;
    }

    private void process(int number) {
        // Process the number
        System.out.println("Processing: " + number);
    }
}
```

**Bad example:**

```java
public class NumberProcessor {
    public void processNumbers(int[] numbers) {
        try {
            int i = 0;
            while (true) {  // Using exception for loop termination
                process(numbers[i++]);
            }
        } catch (ArrayIndexOutOfBoundsException e) {
            // Using exception for normal control flow - bad!
        }
    }

    private void process(int number) {
        System.out.println("Processing: " + number);
    }
}
```

### Example 47: Use Checked Exceptions for Recoverable Conditions and Runtime Exceptions for Programming Errors

Title: Choose the right type of exception for the situation
Description: Checked exceptions force the caller to handle recoverable conditions, while runtime exceptions indicate programming errors.

**Good example:**

```java
public class FileProcessor {
    /**
     * Processes a file. Throws checked exception for recoverable I/O issues.
     */
    public void processFile(String filename) throws FileProcessingException {
        try {
            // File operations that might fail due to external factors
            Files.readAllLines(Paths.get(filename));
        } catch (IOException e) {
            // Wrap in domain-specific checked exception
            throw new FileProcessingException("Failed to process file: " + filename, e);
        }
    }

    /**
     * Validates input parameters. Throws runtime exception for programming errors.
     */
    public void validateInput(String input) {
        if (input == null) {
            // Programming error - should never happen in correct code
            throw new IllegalArgumentException("Input cannot be null");
        }
        if (input.trim().isEmpty()) {
            // Programming error - caller should validate before calling
            throw new IllegalArgumentException("Input cannot be empty");
        }
    }
}

// Custom checked exception for recoverable conditions
class FileProcessingException extends Exception {
    public FileProcessingException(String message, Throwable cause) {
        super(message, cause);
    }
}
```

**Bad example:**

```java
public class FileProcessor {
    // Bad: Using checked exception for programming error
    public void validateInput(String input) throws ValidationException {
        if (input == null) {
            throw new ValidationException("Input cannot be null");  // Should be RuntimeException
        }
    }

    // Bad: Using runtime exception for recoverable condition
    public void processFile(String filename) {
        try {
            Files.readAllLines(Paths.get(filename));
        } catch (IOException e) {
            // Should be checked exception so caller can handle
            throw new RuntimeException("File processing failed", e);
        }
    }
}
```

### Example 48: Favor the Use of Standard Exceptions

Title: Use standard Java exceptions when appropriate
Description: Standard exceptions are familiar to developers and have clear semantics. Don't reinvent the wheel.

**Good example:**

```java
public class Calculator {
    public double divide(double dividend, double divisor) {
        if (divisor == 0.0) {
            throw new ArithmeticException("Division by zero");  // Standard exception
        }
        return dividend / divisor;
    }

    public int getElement(List<Integer> list, int index) {
        Objects.requireNonNull(list, "list");  // Standard NullPointerException
        if (index < 0 || index >= list.size()) {
            throw new IndexOutOfBoundsException("Index: " + index + ", Size: " + list.size());
        }
        return list.get(index);
    }

    public void processPositiveNumber(int number) {
        if (number <= 0) {
            throw new IllegalArgumentException("Number must be positive: " + number);
        }
        // Process the number
    }
}
```

**Bad example:**

```java
public class Calculator {
    public double divide(double dividend, double divisor) {
        if (divisor == 0.0) {
            throw new DivisionByZeroException("Cannot divide by zero");  // Custom exception when standard would do
        }
        return dividend / divisor;
    }

    public int getElement(List<Integer> list, int index) {
        if (list == null) {
            throw new ListIsNullException("List cannot be null");  // Custom exception when standard would do
        }
        if (index < 0 || index >= list.size()) {
            throw new InvalidIndexException("Bad index: " + index);  // Custom exception when standard would do
        }
        return list.get(index);
    }
}

// Unnecessary custom exceptions
class DivisionByZeroException extends RuntimeException {
    public DivisionByZeroException(String message) {
        super(message);
    }
}
class ListIsNullException extends RuntimeException {
    public ListIsNullException(String message) {
        super(message);
    }
}
class InvalidIndexException extends RuntimeException {
    public InvalidIndexException(String message) {
        super(message);
    }
}
```

### Example 49: Include Failure-Capture Information in Detail Messages

Title: Provide detailed, actionable information in exception messages
Description: Exception messages should contain all information needed to diagnose the failure.

**Good example:**

```java
public class BankAccount {
    private double balance;
    private final String accountNumber;

    public BankAccount(String accountNumber, double initialBalance) {
        this.accountNumber = accountNumber;
        this.balance = initialBalance;
    }

    public void withdraw(double amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException(
                String.format("Withdrawal amount must be positive. Account: %s, Amount: %.2f",
                             accountNumber, amount));
        }
        if (amount > balance) {
            throw new InsufficientFundsException(
                String.format("Insufficient funds. Account: %s, Balance: %.2f, Requested: %.2f",
                             accountNumber, balance, amount));
        }
        balance -= amount;
    }

    public void transfer(BankAccount toAccount, double amount) {
        if (toAccount == null) {
            throw new IllegalArgumentException(
                String.format("Destination account cannot be null. Source account: %s, Amount: %.2f",
                             accountNumber, amount));
        }
        if (toAccount.accountNumber.equals(this.accountNumber)) {
            throw new IllegalArgumentException(
                String.format("Cannot transfer to same account. Account: %s, Amount: %.2f",
                             accountNumber, amount));
        }
        withdraw(amount);
        toAccount.deposit(amount);
    }

    public void deposit(double amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException(
                String.format("Deposit amount must be positive. Account: %s, Amount: %.2f",
                             accountNumber, amount));
        }
        balance += amount;
    }
}

class InsufficientFundsException extends RuntimeException {
    public InsufficientFundsException(String message) {
        super(message);
    }
}
```

**Bad example:**

```java
public class BankAccount {
    private double balance;
    private final String accountNumber;

    public void withdraw(double amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException("Invalid amount");  // Too vague
        }
        if (amount > balance) {
            throw new InsufficientFundsException("Not enough money");  // No specific details
        }
        balance -= amount;
    }

    public void transfer(BankAccount toAccount, double amount) {
        if (toAccount == null) {
            throw new IllegalArgumentException("Bad account");  // No context
        }
        if (toAccount.accountNumber.equals(this.accountNumber)) {
            throw new IllegalArgumentException("Error");  // Completely unhelpful
        }
        withdraw(amount);
        toAccount.deposit(amount);
    }
}
```

### Example 50: Don't Ignore Exceptions

Title: Always handle exceptions appropriately, never ignore them silently
Description: Ignoring exceptions can hide bugs and make debugging extremely difficult.

**Good example:**

```java
public class FileManager {
    private static final Logger logger = LoggerFactory.getLogger(FileManager.class);

    public Optional<String> readFileContent(String filename) {
        try {
            return Optional.of(Files.readString(Paths.get(filename)));
        } catch (IOException e) {
            // Log the exception with context
            logger.warn("Failed to read file: {}", filename, e);
            return Optional.empty();  // Return meaningful result
        }
    }

    public void saveToFile(String filename, String content) throws FileOperationException {
        try {
            Files.writeString(Paths.get(filename), content);
            logger.info("Successfully saved content to file: {}", filename);
        } catch (IOException e) {
            // Re-throw as domain-specific exception with context
            throw new FileOperationException("Failed to save content to file: " + filename, e);
        }
    }

    public void cleanupTempFiles(List<String> tempFiles) {
        for (String tempFile : tempFiles) {
            try {
                Files.deleteIfExists(Paths.get(tempFile));
            } catch (IOException e) {
                // Log but continue with other files
                logger.warn("Failed to delete temporary file: {}", tempFile, e);
            }
        }
    }
}

class FileOperationException extends Exception {
    public FileOperationException(String message, Throwable cause) {
        super(message, cause);
    }
}
```

**Bad example:**

```java
public class FileManager {
    public String readFileContent(String filename) {
        try {
            return Files.readString(Paths.get(filename));
        } catch (IOException e) {
            // Silently ignoring exception - very bad!
        }
        return null;  // Caller has no idea what went wrong
    }

    public void saveToFile(String filename, String content) {
        try {
            Files.writeString(Paths.get(filename), content);
        } catch (IOException e) {
            // Empty catch block - hiding the problem
        }
    }

    public void processFiles(List<String> files) {
        for (String file : files) {
            try {
                // Some file processing
                Files.readString(Paths.get(file));
            } catch (Exception e) {
                // Catching Exception is too broad, and then ignoring it
            }
        }
    }
}
```

## Output Format

- **ANALYZE** the current object-oriented design to identify specific issues and categorize them by impact (CRITICAL, MAINTAINABILITY, FLEXIBILITY, CODE_QUALITY) and design area (SOLID violations, code smells, encapsulation problems, inheritance misuse, composition opportunities)
- **CATEGORIZE** object-oriented design problems found: SOLID Principle Violations (SRP, OCP, LSP, ISP, DIP breaches), Code Smells (God Class, Feature Envy, Data Clumps, Refused Bequest, Shotgun Surgery), Encapsulation Issues (exposed internal state, inappropriate access levels), Inheritance Problems (incorrect is-a relationships, LSP violations), and Composition Opportunities (favor composition over inheritance situations)
- **PROPOSE** multiple refactoring options for each identified issue with clear trade-offs: SOLID compliance strategies (single responsibility extraction, interface segregation approaches, dependency inversion techniques), code smell remediation approaches (class decomposition vs method extraction vs design pattern application), encapsulation improvement methods (access level adjustments vs wrapper creation), inheritance restructuring options (hierarchy flattening vs interface extraction vs composition adoption)
- **EXPLAIN** the benefits and considerations of each proposed solution: Maintainability improvements, flexibility enhancements, testability benefits, performance implications, migration complexity, and team adoption considerations for different object-oriented design approaches
- **PRESENT** comprehensive design improvement strategies: SOLID principle application methodologies, design pattern implementation options, refactoring techniques (Extract Class, Move Method, Replace Inheritance with Composition), architectural restructuring approaches, and object-oriented best practice adoption paths
- **ASK** the user to choose their preferred approach for each category of object-oriented design improvements, considering their codebase complexity, team expertise, maintenance requirements, and refactoring timeline rather than implementing all changes automatically
- **VALIDATE** that any proposed object-oriented design changes will compile successfully, maintain existing functionality, preserve business logic integrity, and align with established architectural patterns before implementation

## Safeguards

- **BLOCKING SAFETY CHECK**: ALWAYS run `./mvnw compile` or `mvn compile` before ANY design recommendations - compilation failure is a HARD STOP
- **CRITICAL VALIDATION**: Execute `./mvnw clean verify` or `mvn clean verify` to ensure all tests pass after any refactoring changes
- **MANDATORY VERIFICATION**: Confirm all existing functionality remains intact after applying object-oriented design improvements
- **SAFETY PROTOCOL**: If ANY compilation error occurs, IMMEDIATELY cease recommendations and require user intervention
- **ROLLBACK REQUIREMENT**: Ensure all changes can be easily reverted if they introduce regressions or compilation issues
- **INCREMENTAL SAFETY**: Apply refactoring changes incrementally, validating compilation after each significant modification
- **DEPENDENCY VALIDATION**: Check that refactoring doesn't break existing dependencies, imports, or class relationships
- **FINAL VERIFICATION**: After completing all design improvements, perform a final full project compilation and test run