Designing Clean Classes: The Art of Well-Structured Object-Oriented Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// WARNING: This class violates Single Responsibility Principle
public class UserService {
    
    // Dependencies reveal multiple responsibilities
    private final UserRepository userRepository;      // Persistence concern
    private final PasswordEncoder passwordEncoder;   // Security concern
    private final EmailClient emailClient;           // Communication concern
    private final TemplateEngine templateEngine;     // Presentation concern
    private final AuditLogger auditLogger;           // Compliance concern
    private final MetricsCollector metricsCollector; // Observability concern
    
    // GROUP 1: Authentication methods (Security team stakeholder)
    public User authenticate(String email, String password) { /* ... */ }
    public void resetPassword(String email) { /* ... */ }
    public void changePassword(String oldPass, String newPass) { /* ... */ }
    
    // GROUP 2: Profile methods (Product team stakeholder)
    public void updateProfile(UserProfile profile) { /* ... */ }
    public UserProfile getProfile(Long userId) { /* ... */ }
    public void uploadAvatar(Long userId, byte[] image) { /* ... */ }
    
    // GROUP 3: Communication methods (Marketing team stakeholder)
    public void sendWelcomeEmail(User user) { /* ... */ }
    public void sendPasswordResetEmail(User user, String token) { /* ... */ }
    public void sendMarketingEmail(User user, Campaign campaign) { /* ... */ }
    
    // GROUP 4: Administrative methods (Operations team stakeholder)
    public void suspendUser(Long userId, String reason) { /* ... */ }
    public void deleteUser(Long userId) { /* ... */ }
    public List<User> searchUsers(UserSearchCriteria criteria) { /* ... */ }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

// GOOD: Each class has exactly one reason to change
 
/**
 * Handles user authentication and credential management.
 * Stakeholder: Security Team
 * Changes when: Authentication requirements change
 */
public class UserAuthenticator {
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
    private final AuthenticationEventPublisher eventPublisher;
    
    public AuthenticationResult authenticate(Credentials credentials) { /* ... */ }
    public void initiatePasswordReset(String email) { /* ... */ }
    public void completePasswordReset(String token, String newPassword) { /* ... */ }
}
 
/**
 * Manages user profile data and preferences.
 * Stakeholder: Product Team
 * Changes when: Profile features or user preferences evolve
 */
public class UserProfileManager {
    private final UserRepository userRepository;
    private final ImageProcessor imageProcessor;
    
    public UserProfile getProfile(UserId userId) { /* ... */ }
    public void updateProfile(UserId userId, ProfileUpdateRequest request) { /* ... */ }
    public void updateAvatar(UserId userId, ImageData image) { /* ... */ }
}
 
/**
 * Handles user-facing email communication.
 * Stakeholder: Marketing/Communications Team
 * Changes when: Email templates, branding, or communication strategy changes
 */
public class UserEmailService {
    private final EmailClient emailClient;
    private final TemplateEngine templateEngine;
    
    public void sendWelcomeEmail(User user) { /* ... */ }
    public void sendPasswordResetEmail(User user, ResetToken token) { /* ... */ }
    public void sendCampaignEmail(User user, Campaign campaign) { /* ... */ }
}
 
/**
 * Handles administrative operations on user accounts.
 * Stakeholder: Operations/Trust & Safety Team
 * Changes when: Administrative policies or compliance requirements change
 */
public class UserAdministration {
    private final UserRepository userRepository;
    private final AuditLogger auditLogger;
    
    public void suspendAccount(UserId userId, SuspensionReason reason) { /* ... */ }
    public void terminateAccount(UserId userId) { /* ... */ }
    public SearchResults<User> searchUsers(UserSearchCriteria criteria) { /* ... */ }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

/**
 * Coordinates user operations for external clients.
 * 
 * This facade has one purpose: simplifying access to user-related operations
 * for clients that don't need fine-grained control. It contains NO business
 * logic itself—only orchestration.
 * 
 * Stakeholder: API consumers who want a simple interface
 * Changes when: The public API surface needs to evolve
 */
public class UserFacade {
    private final UserAuthenticator authenticator;
    private final UserProfileManager profileManager;
    private final UserEmailService emailService;
    private final UserAdministration administration;
    
    public UserFacade(
        UserAuthenticator authenticator,
        UserProfileManager profileManager,
        UserEmailService emailService,
        UserAdministration administration
    ) {
        this.authenticator = authenticator;
        this.profileManager = profileManager;
        this.emailService = emailService;
        this.administration = administration;
    }
    
    /**
     * High-level operation that coordinates multiple single-purpose classes.
     * The facade orchestrates; it does not implement business logic.
     */
    public RegistrationResult registerUser(RegistrationRequest request) {
        // Orchestration only—each step delegates to a focused class
        User user = authenticator.createCredentials(request.credentials());
        profileManager.createProfile(user.id(), request.profile());
        emailService.sendWelcomeEmail(user);
        
        return new RegistrationResult(user.id(), Status.SUCCESS);
    }
    
    // Delegate methods for clients needing specific operations
    public AuthenticationResult login(Credentials credentials) {
        return authenticator.authenticate(credentials);
    }
    
    public UserProfile getProfile(UserId userId) {
        return profileManager.getProfile(userId);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

// Each class represents a cohesive domain concern
 
/**
 * Validates that an order meets all business requirements.
 * Pure validation logic—no side effects, easily testable.
 */
public class OrderValidator {
    private final InventoryChecker inventory;
    private final CustomerCreditChecker creditChecker;
    
    public ValidationResult validate(Order order) {
        return ValidationResult.combine(
            validateItemsInStock(order),
            validateCustomerCredit(order),
            validateShippingAddress(order),
            validateOrderLimits(order)
        );
    }
}
 
/**
 * Calculates final order pricing including discounts and taxes.
 * Encapsulates all pricing rules in one place.
 */
public class OrderPricer {
    private final DiscountEngine discountEngine;
    private final TaxCalculator taxCalculator;
    private final ShippingCalculator shippingCalculator;
    
    public PricingBreakdown calculatePrice(Order order) {
        Money subtotal = calculateSubtotal(order.items());
        Money discount = discountEngine.calculateDiscount(order);
        Money shipping = shippingCalculator.calculate(order);
        Money tax = taxCalculator.calculate(order, subtotal.minus(discount));
        
        return new PricingBreakdown(subtotal, discount, shipping, tax);
    }
}
 
/**
 * Handles the persistence and retrieval of orders.
 * All database interaction for orders lives here.
 */
public class OrderRepository {
    private final DataSource dataSource;
    
    public Order save(Order order) { /* ... */ }
    public Optional<Order> findById(OrderId id) { /* ... */ }
    public List<Order> findByCustomer(CustomerId customerId) { /* ... */ }
    public List<Order> findPendingShipment() { /* ... */ }
}
 
/**
 * Coordinates the complete order placement workflow.
 * Orchestration only—no business logic, just sequencing.
 */
public class OrderPlacementService {
    private final OrderValidator validator;
    private final OrderPricer pricer;
    private final OrderRepository repository;
    private final PaymentProcessor paymentProcessor;
    private final OrderEventPublisher eventPublisher;
    
    public PlacementResult placeOrder(OrderRequest request) {
        Order order = Order.fromRequest(request);
        
        ValidationResult validation = validator.validate(order);
        if (!validation.isValid()) {
            return PlacementResult.failed(validation.errors());
        }
        
        PricingBreakdown pricing = pricer.calculatePrice(order);
        order.applyPricing(pricing);
        
        PaymentResult payment = paymentProcessor.process(order);
        if (!payment.isSuccessful()) {
            return PlacementResult.paymentFailed(payment.reason());
        }
        
        Order saved = repository.save(order);
        eventPublisher.publish(new OrderPlacedEvent(saved));
        
        return PlacementResult.success(saved);
    }
}