System Design LLDDesigning Clean Classes

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

LevelIntermediate

Duration75 mins

TopicDesigning Clean Classes

3 / 5

Appropriate Size: Finding the Right Balance for Class Design

The Size Question

"How many lines of code should a class have?"

This is one of the most frequently asked questions about clean class design, and it's the wrong question. Lines of code are a symptom, not the disease. A 500-line class might be perfectly well-designed if those lines form a cohesive whole. A 50-line class might be a maintenance nightmare if it tangles unrelated concerns.

Yet size does matter—just not in the simplistic "lines of code" sense. Appropriate size is about cognitive load: can a developer hold the entire class in their mind at once? This page explores what appropriate size truly means and how to achieve it.

What You Will Master

By the end of this page, you will understand the multiple dimensions of class size, recognize when a class has grown too large or been over-decomposed, and possess practical techniques for sizing classes appropriately.

Dimensions of Class Size

Class size is multidimensional. A class can be 'too large' in several independent ways, each requiring different remedies. Understanding these dimensions helps you diagnose specific problems rather than applying blanket rules.

The Five Dimensions of Class Size

•Lines of Code (LOC) — The raw measure of how much code the class contains. While not definitive, extremely high LOC often signals problems. A 3,000-line class almost certainly does too much.
•Number of Methods — How many operations the class exposes. Excessive methods often indicate multiple responsibilities bundled together. But some domain objects legitimately have many methods (e.g., a rich Date class).
•Number of Instance Variables — The amount of state the class manages. Too many variables suggests the class is tracking multiple, potentially unrelated, concerns.
•Cyclomatic Complexity — The number of independent paths through the code (-the total conditional branching). High complexity makes classes hard to test and understand.
•Cognitive Complexity — How hard the class is to understand. This considers nesting depth, control flow patterns, and conceptual density. A class can be short in LOC but high in cognitive complexity.

Rough Guidelines for Class Size Metrics
Dimension	Green Zone	Yellow Zone	Red Zone
Lines of Code	< 200	200-500	500
Number of Methods	< 10	10-20	20
Instance Variables	< 5	5-10	10
Cyclomatic Complexity (per method)	< 5	5-10	10
Max Nesting Depth	2-3	4	4

Guidelines, Not Rules

These thresholds are heuristics, not laws. A 600-line parser for a complex grammar might be appropriate. A 150-line 'utility' class mixing unrelated functions is not. Always consider context: is the size justified by genuine complexity, or is it accidental complexity that could be reduced?

Signs of Too-Large Classes

Beyond raw metrics, certain patterns in how you work with a class reveal that it has grown too large. These are experiential signals—things you feel while developing and maintaining the code.

Symptoms of Oversized Classes

•Constant Scrolling — You spend more time scrolling to find code than reading or writing it. The class is too large to navigate comfortably.
•Find-in-File Dependency — You can't work on the class without using Ctrl+F constantly. You've lost the mental map of what's where.
•Merge Conflicts — Multiple developers frequently conflict on the same file because independent features touch the same class.
•Test Setup Explosion — Tests require extensive mocking or setup because the class has many dependencies and pathways.
•Description Difficulty — You struggle to describe the class's purpose in one sentence without using 'and' or 'or.'
•Feature Fear — Developers avoid touching the class because changes have unpredictable ripple effects.
•Bug Clustering — Bugs disproportionately appear in this class. Complexity breeds defects.
•Onboarding Bottleneck — New team members take weeks to understand this specific class while grasping others quickly.

GodClass.java
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
/**
 * WARNING: This is an anti-pattern known as a "God Class"
 * 
 * Signs of excessive size:
 * - 47 instance variables tracking unrelated state
 * - 89 methods spanning multiple responsibilities
 * - 4,200 lines of code
 * - 23 direct dependencies (constructor nightmare)
 * - Average method: 65 lines with deep nesting
 */
public class OrderManagementSystem {
    // Customer data section (lines 1-400)
    private Customer customer;
    private Address shippingAddress;
    private Address billingAddress;
    private PaymentMethod paymentMethod;
    // ... 15 more customer-related fields
    
    // Inventory data section (lines 401-800)
    private List<Product> products;
    private Map<String, Integer> stockLevels;
    private Warehouse primaryWarehouse;
    // ... 12 more inventory fields
    
    // Order data section (lines 801-1200)
    private Order currentOrder;
    private List<OrderItem> items;
    private PricingStrategy pricing;
    // ... 10 more order fields
    
    // Shipping data section (lines 1201-1600)
    private Carrier carrier;
    private TrackingInfo tracking;
    // ... 8 more shipping fields
    
    // Payment processing (lines 1601-2500) - 900 LINES
    public PaymentResult processPayment() { /* complex payment logic */ }
    public void handleRefund() { /* refund logic */ }
    public void reconcilePayment() { /* reconciliation */ }
    
    // Order management (lines 2501-3200) - 700 LINES
    public void createOrder() { /* creation logic */ }
    public void modifyOrder() { /* modification */ }
    public void cancelOrder() { /* cancellation */ }
    
    // Inventory management (lines 3201-3800) - 600 LINES
    public void checkStock() { /* stock checking */ }
    public void reserveInventory() { /* reservation */ }
    public void releaseInventory() { /* release */ }
    
    // Shipping orchestration (lines 3801-4200) - 400 LINES
    public void scheduleShipment() { /* scheduling */ }
    public void trackShipment() { /* tracking */ }
    
    // This class should be at least 8 separate classes
}

Signs of Over-Decomposition

The opposite problem—over-decomposition—creates 'class explosion.' When classes are too small, the system's structure becomes obscured by a blizzard of trivial types. Finding where logic lives becomes a treasure hunt through dozens of near-empty classes.

Symptoms of Over-Decomposition

•Method Forwarding Chains — Class A delegates to B, which delegates to C, which does the actual work. You trace through multiple files to find any real logic.
•Classes with One Method — Multiple classes exist solely to wrap a single function. This suggests misidentified boundaries.
•Shotgun Surgery — Simple changes require modifying 10+ files because logic is scattered across too many classes.
•Excessive Indirection — You need to understand 15 classes to follow one user action through the system.
•Name Explosions — You have OrderValidator, OrderValidatorHelper, OrderValidationRunner, OrderValidationResult, OrderValidationContext for what should be one concern.
•Assembly Nightmares — Dependency injection configuration becomes hundreds of lines wiring trivial classes together.
•Anemic Domain Objects — Domain classes are pure data containers with zero behavior; all logic lives in service classes.

OverDecomposed.java
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
// ❌ BAD: Over-decomposition - these should be ONE class
 
class EmailValidator {
    private final EmailSyntaxChecker syntaxChecker;
    private final EmailDomainValidator domainValidator;
    
    public boolean validate(String email) {
        return syntaxChecker.check(email) && domainValidator.validate(email);
    }
}
 
class EmailSyntaxChecker {
    public boolean check(String email) {
        return email.contains("@");  // One line of actual logic
    }
}
 
class EmailDomainValidator {
    private final DomainExistenceVerifier verifier;
    
    public boolean validate(String email) {
        return verifier.verify(extractDomain(email));
    }
    
    private String extractDomain(String email) {
        return email.split("@")[1];  // One line of actual logic
    }
}
 
class DomainExistenceVerifier {
    public boolean verify(String domain) {
        // DNS lookup - the only substantial logic
    }
}
 
// ✅ BETTER: Consolidated into one cohesive class
 
class EmailValidator {
    public ValidationResult validate(String email) {
        if (!hasSyntax(email)) {
            return ValidationResult.invalid("Missing @ symbol");
        }
        
        String domain = extractDomain(email);
        if (!domainExists(domain)) {
            return ValidationResult.invalid("Domain does not exist");
        }
        
        return ValidationResult.valid();
    }
    
    private boolean hasSyntax(String email) {
        return email.contains("@") && email.indexOf("@") > 0;
    }
    
    private String extractDomain(String email) {
        return email.split("@")[1];
    }
    
    private boolean domainExists(String domain) {
        // DNS lookup
    }
}

The Cohesion Test

If separating two pieces of code means they constantly need to call each other, or one is meaningless without the other, they probably belong together. Cohesion trumps small-for-small's-sake.

Finding the Goldilocks Zone

Between the god class and class explosion lies the Goldilocks zone—classes that are 'just right.' These classes are small enough to understand at a glance but large enough to contain meaningful, cohesive functionality.

Characteristics of Well-Sized Classes

•Fits in Working Memory — A developer can understand the entire class without external notes. This typically means they can hold the class's purpose, state, and key behaviors in mind simultaneously.
•Self-Contained Understanding — You can understand what the class does without reading its dependencies. The class name, field names, and method names tell a complete story.
•Obvious Testing — It's immediately clear how to test the class. You can enumerate test cases without analysis paralysis.
•Change Isolation — Modifications to this class don't cascade into unrelated areas. You can change implementation details without touching other classes.
•Meaningful Abstraction — The class represents a concept worth naming. It's not just a mechanical grouping of functions but captures a domain or design idea.

ShippingCalculator.java
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
/**
 * Calculates shipping costs for orders.
 * 
 * This class is well-sized because:
 * - Single, clear responsibility (shipping cost calculation)
 * - Reasonable number of methods (5 public, 3 private)
 * - Limited state (3 dependencies)
 * - Each method is focused and testable
 * - Total: ~80 lines of meaningful code
 */
public class ShippingCalculator {
    
    private final WeightPricingTable weightPricing;
    private final DistanceCalculator distanceCalculator;
    private final CarrierRates carrierRates;
    
    public ShippingCalculator(
        WeightPricingTable weightPricing,
        DistanceCalculator distanceCalculator,
        CarrierRates carrierRates
    ) {
        this.weightPricing = weightPricing;
        this.distanceCalculator = distanceCalculator;
        this.carrierRates = carrierRates;
    }
    
    // Public API: Clear, focused methods
    
    public Money calculateStandardShipping(Order order) {
        Weight totalWeight = calculateTotalWeight(order);
        Distance distance = calculateDistance(order);
        return computeCost(totalWeight, distance, ShippingTier.STANDARD);
    }
    
    public Money calculateExpressShipping(Order order) {
        Weight totalWeight = calculateTotalWeight(order);
        Distance distance = calculateDistance(order);
        return computeCost(totalWeight, distance, ShippingTier.EXPRESS);
    }
    
    public Money calculateOvernightShipping(Order order) {
        Weight totalWeight = calculateTotalWeight(order);
        Distance distance = calculateDistance(order);
        return computeCost(totalWeight, distance, ShippingTier.OVERNIGHT);
    }
    
    public List<ShippingOption> getAllOptions(Order order) {
        return List.of(
            new ShippingOption(ShippingTier.STANDARD, calculateStandardShipping(order)),
            new ShippingOption(ShippingTier.EXPRESS, calculateExpressShipping(order)),
            new ShippingOption(ShippingTier.OVERNIGHT, calculateOvernightShipping(order))
        );
    }
    
    public boolean isEligibleForFreeShipping(Order order) {
        return order.subtotal().isGreaterThan(Money.of(75)) 
            && calculateTotalWeight(order).isLessThan(Weight.pounds(50));
    }
    
    // Private helpers: Implementation details
    
    private Weight calculateTotalWeight(Order order) {
        return order.items().stream()
            .map(item -> item.product().weight().times(item.quantity()))
            .reduce(Weight.ZERO, Weight::add);
    }
    
    private Distance calculateDistance(Order order) {
        return distanceCalculator.between(
            order.warehouse().location(),
            order.shippingAddress()
        );
    }
    
    private Money computeCost(Weight weight, Distance distance, ShippingTier tier) {
        Money baseCost = weightPricing.priceFor(weight);
        Money distanceCost = carrierRates.rateFor(distance, tier);
        return baseCost.add(distanceCost);
    }
}

Practical Sizing Strategies

Rather than measuring lines of code, use these practical strategies to right-size classes during design and refactoring:

Class Sizing Techniques

•The Newspaper Test — Read the class like a newspaper article. The class name is the headline, public methods are the lead paragraphs, private methods are the details. If the headline doesn't match the story, or the story is actually multiple stories, restructure.
•The Explanation Test — Explain the class to a colleague in one breath. If you need to pause for 'and also it does...' multiple times, the class is too large. If you struggle to fill a sentence, it may be too small.
•The Test Isolation Test — Write unit tests. If you can test each method with minimal setup and no complex mocking, the class is well-sized. If testing requires elaborate scaffolding, it's too coupled or too large.
•The Change Frequency Test — Track which classes change together. If two areas of a class always change independently, consider splitting. If two classes always change together, consider merging.
•The Scroll Test (Heuristic) — Can you see the entire public interface without scrolling? This crude heuristic often points to classes that have grown beyond comprehensibility.

Context Matters

A command-line utility might have a 30-line main class handling all logic. An enterprise application might have 300-line classes for complex domain rules. Neither is inherently wrong. Size appropriateness depends on domain complexity, team conventions, and system requirements.

Refactoring Oversized Classes

When you've identified a class that's grown too large, systematic refactoring reduces it to appropriate size. The key is incremental extraction—pulling out cohesive pieces one at a time while maintaining working software.

Incremental Extraction Process

•Identify Method Clusters — Mark methods that work together on the same subset of fields. These clusters are extraction candidates.
•Find Feature Envy — Identify methods that primarily use data from other objects. These often belong in those other objects.
•Extract to New Class — Choose one cluster and extract it to a new, well-named class. The original class becomes a client of the extracted class.
•Move Fields — Fields used only by the extracted methods move to the new class. This reduces the original class's state responsibility.
•Update Tests — Add unit tests for the new class. Existing tests for the original class should still pass (coverage moves but doesn't disappear).
•Repeat — Continue extracting clusters until the original class is focused on a single responsibility.

ExtractRefactoring.java
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
// BEFORE: 400-line class with payment and notification mixed
 
class OrderProcessor {
    // Fields for order processing
    private OrderRepository orderRepository;
    private InventoryService inventoryService;
    
    // Fields for payment (extraction candidate)
    private PaymentGateway paymentGateway;
    private FraudDetector fraudDetector;
    private TransactionLogger transactionLogger;
    
    // Fields for notification (extraction candidate)
    private EmailService emailService;
    private SmsService smsService;
    private NotificationPreferences preferences;
    
    public void processOrder(Order order) {
        // Order logic: ~100 lines
        // Payment logic: ~150 lines (cluster 1)
        // Notification logic: ~100 lines (cluster 2)
    }
}
 
 
// AFTER: Three focused classes
 
class OrderProcessor {
    private final OrderRepository orderRepository;
    private final InventoryService inventoryService;
    private final PaymentProcessor paymentProcessor;  // extracted
    private final OrderNotifier orderNotifier;        // extracted
    
    public void processOrder(Order order) {
        validateAndReserve(order);
        paymentProcessor.processPayment(order);
        orderNotifier.notifyOrderPlaced(order);
    }
}
 
class PaymentProcessor {  // Extracted from OrderProcessor
    private final PaymentGateway paymentGateway;
    private final FraudDetector fraudDetector;
    private final TransactionLogger transactionLogger;
    
    public PaymentResult processPayment(Order order) {
        // Payment logic: focused, testable, ~100 lines
    }
}
 
class OrderNotifier {  // Extracted from OrderProcessor
    private final EmailService emailService;
    private final SmsService smsService;
    private final NotificationPreferences preferences;
    
    public void notifyOrderPlaced(Order order) {
        // Notification logic: focused, testable, ~80 lines
    }
}

When Size Guidelines Don't Apply

Certain classes legitimately exceed typical size guidelines. Recognizing these exceptions prevents unnecessary refactoring that would actually harm the design.

Legitimate Exceptions to Size Guidelines

•Rich Domain Objects — A Date or Money class might have 50+ methods (arithmetic, comparison, formatting, parsing) yet remain cohesive. Each method operates on the same core concept.
•Parsers and Interpreters — Parsing complex formats (programming languages, configuration files, data formats) often requires substantial code. The methods are cohesive around the parsing task.
•State Machines — Classes implementing complex state machines naturally have many transition methods. Splitting by state often obscures the overall machine logic.
•Mathematical Libraries — A Matrix class or ComplexNumber class might have many operations that all operate on the same mathematical structure.
•Test Classes — Test classes may be large due to comprehensive coverage. This is acceptable as test methods are independent and don't create maintenance issues.
•Generated Code — ORM entities, protocol buffer classes, and other generated code often violate size guidelines. This is acceptable since you don't maintain the generation template, not each generated file.

The Cohesion Exception

A large class is acceptable if every method intimately operates on the same core state and concept. The question isn't 'how many lines?' but 'do all these methods belong together?' If yes, size is justified.

Summary: Right-Sized Classes

Class size is about cognitive manageability, not arbitrary line counts. Well-sized classes can be understood in their entirety and changed with confidence.

Key Takeaways

•Size has multiple dimensions — Lines of code, method count, instance variables, complexity, and cognitive load all matter.
•Too large creates god classes — Symptoms include constant scrolling, merge conflicts, test explosions, and bug clustering.
•Too small creates class explosion — Symptoms include method forwarding chains, shotgun surgery, and excessive indirection.
•The Goldilocks zone fits working memory — A developer can understand the entire class without notes.
•Use practical tests — The newspaper, explanation, test isolation, and change frequency tests guide sizing decisions.
•Extract incrementally — Reduce oversized classes by extracting cohesive method clusters one at a time.
•Cohesive exceptions are valid — Rich domain objects, parsers, and mathematical libraries may legitimately exceed guidelines.

What's next:

Size is closely related to the next topic: cohesive members. A well-sized class achieves that size through cohesion—every member (field and method) working together toward the same purpose. The next page explores what cohesion means and how to achieve it.

Page Complete

You now understand the multi-dimensional nature of class size and how to find the Goldilocks zone. Next, we'll explore cohesion—the glue that binds class members into a unified whole.

3 / 5

Loading learning content...

System Design LLDDesigning Clean Classes

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

LevelIntermediate

Duration75 mins

TopicDesigning Clean Classes

3 / 5

Appropriate Size: Finding the Right Balance for Class Design

The Size Question

"How many lines of code should a class have?"

What You Will Master

Dimensions of Class Size

The Five Dimensions of Class Size

•Lines of Code (LOC) — The raw measure of how much code the class contains. While not definitive, extremely high LOC often signals problems. A 3,000-line class almost certainly does too much.
•Number of Methods — How many operations the class exposes. Excessive methods often indicate multiple responsibilities bundled together. But some domain objects legitimately have many methods (e.g., a rich Date class).
•Number of Instance Variables — The amount of state the class manages. Too many variables suggests the class is tracking multiple, potentially unrelated, concerns.
•Cyclomatic Complexity — The number of independent paths through the code (-the total conditional branching). High complexity makes classes hard to test and understand.
•Cognitive Complexity — How hard the class is to understand. This considers nesting depth, control flow patterns, and conceptual density. A class can be short in LOC but high in cognitive complexity.

Rough Guidelines for Class Size Metrics
Dimension	Green Zone	Yellow Zone	Red Zone
Lines of Code	< 200	200-500	500
Number of Methods	< 10	10-20	20
Instance Variables	< 5	5-10	10
Cyclomatic Complexity (per method)	< 5	5-10	10
Max Nesting Depth	2-3	4	4

Guidelines, Not Rules

Signs of Too-Large Classes

Beyond raw metrics, certain patterns in how you work with a class reveal that it has grown too large. These are experiential signals—things you feel while developing and maintaining the code.

Symptoms of Oversized Classes

•Constant Scrolling — You spend more time scrolling to find code than reading or writing it. The class is too large to navigate comfortably.
•Find-in-File Dependency — You can't work on the class without using Ctrl+F constantly. You've lost the mental map of what's where.
•Merge Conflicts — Multiple developers frequently conflict on the same file because independent features touch the same class.
•Test Setup Explosion — Tests require extensive mocking or setup because the class has many dependencies and pathways.
•Description Difficulty — You struggle to describe the class's purpose in one sentence without using 'and' or 'or.'
•Feature Fear — Developers avoid touching the class because changes have unpredictable ripple effects.
•Bug Clustering — Bugs disproportionately appear in this class. Complexity breeds defects.
•Onboarding Bottleneck — New team members take weeks to understand this specific class while grasping others quickly.

GodClass.java
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
/**
 * WARNING: This is an anti-pattern known as a "God Class"
 * 
 * Signs of excessive size:
 * - 47 instance variables tracking unrelated state
 * - 89 methods spanning multiple responsibilities
 * - 4,200 lines of code
 * - 23 direct dependencies (constructor nightmare)
 * - Average method: 65 lines with deep nesting
 */
public class OrderManagementSystem {
    // Customer data section (lines 1-400)
    private Customer customer;
    private Address shippingAddress;
    private Address billingAddress;
    private PaymentMethod paymentMethod;
    // ... 15 more customer-related fields
    
    // Inventory data section (lines 401-800)
    private List<Product> products;
    private Map<String, Integer> stockLevels;
    private Warehouse primaryWarehouse;
    // ... 12 more inventory fields
    
    // Order data section (lines 801-1200)
    private Order currentOrder;
    private List<OrderItem> items;
    private PricingStrategy pricing;
    // ... 10 more order fields
    
    // Shipping data section (lines 1201-1600)
    private Carrier carrier;
    private TrackingInfo tracking;
    // ... 8 more shipping fields
    
    // Payment processing (lines 1601-2500) - 900 LINES
    public PaymentResult processPayment() { /* complex payment logic */ }
    public void handleRefund() { /* refund logic */ }
    public void reconcilePayment() { /* reconciliation */ }
    
    // Order management (lines 2501-3200) - 700 LINES
    public void createOrder() { /* creation logic */ }
    public void modifyOrder() { /* modification */ }
    public void cancelOrder() { /* cancellation */ }
    
    // Inventory management (lines 3201-3800) - 600 LINES
    public void checkStock() { /* stock checking */ }
    public void reserveInventory() { /* reservation */ }
    public void releaseInventory() { /* release */ }
    
    // Shipping orchestration (lines 3801-4200) - 400 LINES
    public void scheduleShipment() { /* scheduling */ }
    public void trackShipment() { /* tracking */ }
    
    // This class should be at least 8 separate classes
}

Signs of Over-Decomposition

Symptoms of Over-Decomposition

•Method Forwarding Chains — Class A delegates to B, which delegates to C, which does the actual work. You trace through multiple files to find any real logic.
•Classes with One Method — Multiple classes exist solely to wrap a single function. This suggests misidentified boundaries.
•Shotgun Surgery — Simple changes require modifying 10+ files because logic is scattered across too many classes.
•Excessive Indirection — You need to understand 15 classes to follow one user action through the system.
•Name Explosions — You have OrderValidator, OrderValidatorHelper, OrderValidationRunner, OrderValidationResult, OrderValidationContext for what should be one concern.
•Assembly Nightmares — Dependency injection configuration becomes hundreds of lines wiring trivial classes together.
•Anemic Domain Objects — Domain classes are pure data containers with zero behavior; all logic lives in service classes.

OverDecomposed.java
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
// ❌ BAD: Over-decomposition - these should be ONE class
 
class EmailValidator {
    private final EmailSyntaxChecker syntaxChecker;
    private final EmailDomainValidator domainValidator;
    
    public boolean validate(String email) {
        return syntaxChecker.check(email) && domainValidator.validate(email);
    }
}
 
class EmailSyntaxChecker {
    public boolean check(String email) {
        return email.contains("@");  // One line of actual logic
    }
}
 
class EmailDomainValidator {
    private final DomainExistenceVerifier verifier;
    
    public boolean validate(String email) {
        return verifier.verify(extractDomain(email));
    }
    
    private String extractDomain(String email) {
        return email.split("@")[1];  // One line of actual logic
    }
}
 
class DomainExistenceVerifier {
    public boolean verify(String domain) {
        // DNS lookup - the only substantial logic
    }
}
 
// ✅ BETTER: Consolidated into one cohesive class
 
class EmailValidator {
    public ValidationResult validate(String email) {
        if (!hasSyntax(email)) {
            return ValidationResult.invalid("Missing @ symbol");
        }
        
        String domain = extractDomain(email);
        if (!domainExists(domain)) {
            return ValidationResult.invalid("Domain does not exist");
        }
        
        return ValidationResult.valid();
    }
    
    private boolean hasSyntax(String email) {
        return email.contains("@") && email.indexOf("@") > 0;
    }
    
    private String extractDomain(String email) {
        return email.split("@")[1];
    }
    
    private boolean domainExists(String domain) {
        // DNS lookup
    }
}

The Cohesion Test

If separating two pieces of code means they constantly need to call each other, or one is meaningless without the other, they probably belong together. Cohesion trumps small-for-small's-sake.

Finding the Goldilocks Zone

Characteristics of Well-Sized Classes

•Fits in Working Memory — A developer can understand the entire class without external notes. This typically means they can hold the class's purpose, state, and key behaviors in mind simultaneously.
•Self-Contained Understanding — You can understand what the class does without reading its dependencies. The class name, field names, and method names tell a complete story.
•Obvious Testing — It's immediately clear how to test the class. You can enumerate test cases without analysis paralysis.
•Change Isolation — Modifications to this class don't cascade into unrelated areas. You can change implementation details without touching other classes.
•Meaningful Abstraction — The class represents a concept worth naming. It's not just a mechanical grouping of functions but captures a domain or design idea.

ShippingCalculator.java
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
/**
 * Calculates shipping costs for orders.
 * 
 * This class is well-sized because:
 * - Single, clear responsibility (shipping cost calculation)
 * - Reasonable number of methods (5 public, 3 private)
 * - Limited state (3 dependencies)
 * - Each method is focused and testable
 * - Total: ~80 lines of meaningful code
 */
public class ShippingCalculator {
    
    private final WeightPricingTable weightPricing;
    private final DistanceCalculator distanceCalculator;
    private final CarrierRates carrierRates;
    
    public ShippingCalculator(
        WeightPricingTable weightPricing,
        DistanceCalculator distanceCalculator,
        CarrierRates carrierRates
    ) {
        this.weightPricing = weightPricing;
        this.distanceCalculator = distanceCalculator;
        this.carrierRates = carrierRates;
    }
    
    // Public API: Clear, focused methods
    
    public Money calculateStandardShipping(Order order) {
        Weight totalWeight = calculateTotalWeight(order);
        Distance distance = calculateDistance(order);
        return computeCost(totalWeight, distance, ShippingTier.STANDARD);
    }
    
    public Money calculateExpressShipping(Order order) {
        Weight totalWeight = calculateTotalWeight(order);
        Distance distance = calculateDistance(order);
        return computeCost(totalWeight, distance, ShippingTier.EXPRESS);
    }
    
    public Money calculateOvernightShipping(Order order) {
        Weight totalWeight = calculateTotalWeight(order);
        Distance distance = calculateDistance(order);
        return computeCost(totalWeight, distance, ShippingTier.OVERNIGHT);
    }
    
    public List<ShippingOption> getAllOptions(Order order) {
        return List.of(
            new ShippingOption(ShippingTier.STANDARD, calculateStandardShipping(order)),
            new ShippingOption(ShippingTier.EXPRESS, calculateExpressShipping(order)),
            new ShippingOption(ShippingTier.OVERNIGHT, calculateOvernightShipping(order))
        );
    }
    
    public boolean isEligibleForFreeShipping(Order order) {
        return order.subtotal().isGreaterThan(Money.of(75)) 
            && calculateTotalWeight(order).isLessThan(Weight.pounds(50));
    }
    
    // Private helpers: Implementation details
    
    private Weight calculateTotalWeight(Order order) {
        return order.items().stream()
            .map(item -> item.product().weight().times(item.quantity()))
            .reduce(Weight.ZERO, Weight::add);
    }
    
    private Distance calculateDistance(Order order) {
        return distanceCalculator.between(
            order.warehouse().location(),
            order.shippingAddress()
        );
    }
    
    private Money computeCost(Weight weight, Distance distance, ShippingTier tier) {
        Money baseCost = weightPricing.priceFor(weight);
        Money distanceCost = carrierRates.rateFor(distance, tier);
        return baseCost.add(distanceCost);
    }
}

Practical Sizing Strategies

Rather than measuring lines of code, use these practical strategies to right-size classes during design and refactoring:

Class Sizing Techniques

•The Newspaper Test — Read the class like a newspaper article. The class name is the headline, public methods are the lead paragraphs, private methods are the details. If the headline doesn't match the story, or the story is actually multiple stories, restructure.
•The Explanation Test — Explain the class to a colleague in one breath. If you need to pause for 'and also it does...' multiple times, the class is too large. If you struggle to fill a sentence, it may be too small.
•The Test Isolation Test — Write unit tests. If you can test each method with minimal setup and no complex mocking, the class is well-sized. If testing requires elaborate scaffolding, it's too coupled or too large.
•The Change Frequency Test — Track which classes change together. If two areas of a class always change independently, consider splitting. If two classes always change together, consider merging.
•The Scroll Test (Heuristic) — Can you see the entire public interface without scrolling? This crude heuristic often points to classes that have grown beyond comprehensibility.

Context Matters

Refactoring Oversized Classes

Incremental Extraction Process

•Identify Method Clusters — Mark methods that work together on the same subset of fields. These clusters are extraction candidates.
•Find Feature Envy — Identify methods that primarily use data from other objects. These often belong in those other objects.
•Extract to New Class — Choose one cluster and extract it to a new, well-named class. The original class becomes a client of the extracted class.
•Move Fields — Fields used only by the extracted methods move to the new class. This reduces the original class's state responsibility.
•Update Tests — Add unit tests for the new class. Existing tests for the original class should still pass (coverage moves but doesn't disappear).
•Repeat — Continue extracting clusters until the original class is focused on a single responsibility.

ExtractRefactoring.java
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
// BEFORE: 400-line class with payment and notification mixed
 
class OrderProcessor {
    // Fields for order processing
    private OrderRepository orderRepository;
    private InventoryService inventoryService;
    
    // Fields for payment (extraction candidate)
    private PaymentGateway paymentGateway;
    private FraudDetector fraudDetector;
    private TransactionLogger transactionLogger;
    
    // Fields for notification (extraction candidate)
    private EmailService emailService;
    private SmsService smsService;
    private NotificationPreferences preferences;
    
    public void processOrder(Order order) {
        // Order logic: ~100 lines
        // Payment logic: ~150 lines (cluster 1)
        // Notification logic: ~100 lines (cluster 2)
    }
}
 
 
// AFTER: Three focused classes
 
class OrderProcessor {
    private final OrderRepository orderRepository;
    private final InventoryService inventoryService;
    private final PaymentProcessor paymentProcessor;  // extracted
    private final OrderNotifier orderNotifier;        // extracted
    
    public void processOrder(Order order) {
        validateAndReserve(order);
        paymentProcessor.processPayment(order);
        orderNotifier.notifyOrderPlaced(order);
    }
}
 
class PaymentProcessor {  // Extracted from OrderProcessor
    private final PaymentGateway paymentGateway;
    private final FraudDetector fraudDetector;
    private final TransactionLogger transactionLogger;
    
    public PaymentResult processPayment(Order order) {
        // Payment logic: focused, testable, ~100 lines
    }
}
 
class OrderNotifier {  // Extracted from OrderProcessor
    private final EmailService emailService;
    private final SmsService smsService;
    private final NotificationPreferences preferences;
    
    public void notifyOrderPlaced(Order order) {
        // Notification logic: focused, testable, ~80 lines
    }
}

When Size Guidelines Don't Apply

Certain classes legitimately exceed typical size guidelines. Recognizing these exceptions prevents unnecessary refactoring that would actually harm the design.

Legitimate Exceptions to Size Guidelines

•Rich Domain Objects — A Date or Money class might have 50+ methods (arithmetic, comparison, formatting, parsing) yet remain cohesive. Each method operates on the same core concept.
•Parsers and Interpreters — Parsing complex formats (programming languages, configuration files, data formats) often requires substantial code. The methods are cohesive around the parsing task.
•State Machines — Classes implementing complex state machines naturally have many transition methods. Splitting by state often obscures the overall machine logic.
•Mathematical Libraries — A Matrix class or ComplexNumber class might have many operations that all operate on the same mathematical structure.
•Test Classes — Test classes may be large due to comprehensive coverage. This is acceptable as test methods are independent and don't create maintenance issues.
•Generated Code — ORM entities, protocol buffer classes, and other generated code often violate size guidelines. This is acceptable since you don't maintain the generation template, not each generated file.

The Cohesion Exception

Summary: Right-Sized Classes

Class size is about cognitive manageability, not arbitrary line counts. Well-sized classes can be understood in their entirety and changed with confidence.

Key Takeaways

•Size has multiple dimensions — Lines of code, method count, instance variables, complexity, and cognitive load all matter.
•Too large creates god classes — Symptoms include constant scrolling, merge conflicts, test explosions, and bug clustering.
•Too small creates class explosion — Symptoms include method forwarding chains, shotgun surgery, and excessive indirection.
•The Goldilocks zone fits working memory — A developer can understand the entire class without notes.
•Use practical tests — The newspaper, explanation, test isolation, and change frequency tests guide sizing decisions.
•Extract incrementally — Reduce oversized classes by extracting cohesive method clusters one at a time.
•Cohesive exceptions are valid — Rich domain objects, parsers, and mathematical libraries may legitimately exceed guidelines.

What's next:

Page Complete

You now understand the multi-dimensional nature of class size and how to find the Goldilocks zone. Next, we'll explore cohesion—the glue that binds class members into a unified whole.

3 / 5