Designing Clean Classes - Learning Module

Loading content...

0/246

Class Design Checklist: A Practical Guide to Clean Classes

From Principles to Practice

You've now explored the foundational principles of clean class design: single purpose, meaningful names, appropriate size, and cohesive members. Each principle is essential, but their power emerges when applied together systematically.

This page consolidates everything into an actionable checklist—a practical tool you can use every time you design a new class, review existing code, or refactor a problematic component. This checklist isn't meant to be memorized; it's meant to be used. Bookmark it. Print it. Refer to it until these principles become second nature.

What You Will Gain

By the end of this page, you will have a comprehensive, systematic checklist for evaluating class design quality, practical workflows for applying these principles during development, and clear criteria for code reviews focused on class-level design.

The Complete Class Design Checklist

Use this checklist when designing new classes or reviewing existing ones. A well-designed class should satisfy all or nearly all of these criteria:

Single Purpose (Single Responsibility)

•☐ One reason to change — The class serves exactly one stakeholder or requirement source.
•☐ Describable in one sentence — You can explain the class's purpose without using 'and' or 'or.'
•☐ No method grouping — Methods don't cluster into independent groups with separate concerns.
•☐ Coherent dependencies — All dependencies serve the same purpose; no unrelated imports.
•☐ Changes are isolated — Modifying this class doesn't risk breaking unrelated features.

Meaningful Name

•☐ Intention-revealing — The name predicts the class's behavior without reading implementation.
•☐ Domain-grounded — The name uses business vocabulary, not technical jargon.
•☐ Specific, not generic — No Manager, Helper, Utils, Handler without specific context.
•☐ Pronounceable — The name can be discussed verbally without spelling it out.
•☐ Honest — The name accurately describes current behavior, not original intention.

Appropriate Size

•☐ Fits in working memory — A developer can understand the class without notes.
•☐ No constant scrolling — You can navigate the class without Find-in-File dependency.
•☐ Reasonable metrics — LOC < 500, methods < 20, instance variables < 10 (guidelines, not rules).
•☐ Not over-decomposed — The class has substance; not a one-method wrapper or pure delegation.
•☐ Tests aren't painful — Unit tests don't require elaborate setup or extensive mocking.

Cohesive Members

•☐ Methods use shared state — Each method operates on most instance variables.
•☐ No orphan variables — Every instance variable is used by multiple methods.
•☐ No method cliques — You can't partition methods into groups that ignore each other's state.
•☐ Functional cohesion — All elements contribute to a single, well-defined task.
•☐ Hard to split — Separating the class would require duplicating fields or creating tight coupling.

Quick Reference Card

Use this condensed table for rapid evaluation during code reviews or design sessions:

Class Design Quality Indicators
Principle	Green Flag ✓	Red Flag ✗
Single Purpose	One stakeholder, one reason to change	Multiple unrelated responsibilities
Meaningful Name	Predicts behavior, uses domain terms	Generic suffix, technical jargon
Appropriate Size	Fits in mind, tests easily	Constant scrolling, test explosions
Cohesive Members	Methods share state, hard to split	Orphan variables, method cliques

Rule of Thumb Metrics
Metric	Healthy Range	Warning Threshold
Lines of Code	50-200	500
Public Methods	3-10	20
Instance Variables	2-5	10
Constructor Parameters	1-4	6
Dependencies (imports)	3-7	12
LCOM3 Score	1	1

Workflow: Designing New Classes

When creating a new class from scratch, follow this workflow to build in quality from the start:

New Class Design Process

•Define the responsibility — Write one sentence describing what this class will do. 'This class validates email addresses for syntax and deliverability.' If you need 'and' or 'or,' you may need multiple classes.
•Choose a precise name — Derive the name from the responsibility. EmailValidator. Verify it's specific (not Validator), domain-grounded (not StringChecker), and intention-revealing.
•Identify the core state — List the instance variables needed to fulfill the responsibility. Keep this minimal. Each variable should be used by multiple methods.
•Draft the public API — List the public methods. Each method should operate on the core state. If a method doesn't use any instance variables, question whether it belongs here.
•Verify cohesion — Draw the method-variable matrix mentally. Does every method touch most variables? Are there any orphan variables or method cliques?
•Estimate size — Will the implementation exceed 300 lines? If so, consider whether there are hidden sub-responsibilities that should be extracted.
•Write tests first — If testing is painful (lots of mocking, complex setup), the design may need revision. Tests often reveal design problems before implementation.
•Implement and review — Implement the class, then run through the checklist. Refactor before committing if any criteria fail.

The 5-Minute Design

Before writing any code, spend 5 minutes with paper or a whiteboard. Write the class name, list its fields, list its methods. Does it look cohesive? Is the name accurate? This small investment prevents hours of refactoring later.

Workflow: Reviewing Existing Classes

When evaluating an existing class—whether your own in review or legacy code you've inherited—use this systematic assessment:

Existing Class Assessment Process

•Read the class name — Does it predict the behavior you find inside? If not, flag for renaming.
•Count the metrics — Check LOC, method count, field count. If any exceed thresholds, investigate further.
•Scan the imports — Are dependencies from multiple unrelated domains (database, UI, email, encryption)? Flag for SRP review.
•Identify method groups — Can you mentally cluster methods by which fields they use? Multiple clusters = low cohesion.
•Look for Feature Envy — Do methods mostly operate on parameters or collaborator data rather than own state? Consider moving methods.
•Check for flag parameters — Methods with boolean or enum parameters that change behavior fundamentally suggest merged responsibilities.
•Run the tests — How hard is the test setup? Difficulty testing often reveals design problems.
•Summarize in one sentence — Try to describe what the class does. Difficulty indicates unclear purpose.

CodeReviewNotes.md
## Class Review: OrderProcessor
 
### Metrics
- LOC: 847 ⚠️ (exceeds 500)
- Methods: 23 ⚠️ (exceeds 20)
- Instance Variables: 12 ⚠️ (exceeds 10)
 
### Single Purpose
❌ Class handles: order validation, pricing, inventory, AND notifications
Recommendation: Extract OrderValidator, OrderPricer, InventoryReserver, OrderNotifier
 
### Name Quality
⚠️ "Processor" is generic
Recommendation: If kept as coordinator, rename to OrderCoordinator
 
### Cohesion Analysis
❌ Method cliques detected:
  - Clique A (lines 50-200): validation methods, use fields 1-3
  - Clique B (lines 200-400): pricing methods, use fields 4-6
  - Clique C (lines 400-600): notification methods, use fields 7-9
LCOM3 ≈ 3 (should be 1)
 
### Recommendation
HIGH PRIORITY: Extract into 4 focused classes

Code Review Focus Areas

When conducting code reviews with a focus on class design quality, look for these specific issues:

Code Review Feedback Templates

•SRP Violation: 'This class handles both X and Y. Consider extracting Y into a separate class so each has a single reason to change.'
•Generic Name: 'The name DataHandler doesn't reveal intent. What data? What handling? Consider CustomerProfileSerializer or similar.'
•Size Concern: 'At 600+ lines, this class is difficult to navigate. Can we identify extraction opportunities for method clusters?'
•Low Cohesion: 'I notice methods A, B, C only use fields X, Y while methods D, E, F only use fields W, Z. Could these be separate classes?'
•Feature Envy: 'This method accesses 5 getters on Order but no local state. Should this method move to the Order class?'
•Orphan Variable: 'Field lastUpdated is only used by getLastUpdated(). Is this field necessary, or should it be computed?'
•Excessive Dependencies: '12 constructor parameters is a lot. Could some be grouped or could the class be split?'

Constructive Reviews

Frame feedback constructively with specific suggestions. Instead of 'This class is too big,' try 'At 700 lines, I found it hard to navigate. The payment methods (lines 200-400) seem separable—would a PaymentProcessor extraction help?'

Refactoring Decision Guide

When problems are identified, these common refactoring patterns address specific issues:

Problem → Refactoring Mapping
Problem Identified	Refactoring	Outcome
Multiple responsibilities	Extract Class	Separate classes, each with single purpose
Method uses another object's data	Move Method	Method lives with its data
Many constructor parameters	Introduce Parameter Object	Grouped parameters, cleaner API
Class mostly delegates	Remove Middleman	Clients talk directly to real worker
Method groups use different fields	Extract Class per group	High cohesion in each new class
Generic name hides purpose	Rename Class	Intent revealed by name
Too many switch/case blocks	Replace Conditional with Polymorphism	Strategy classes, cleaner dispatch
Related fields scattered	Extract Value Object	Encapsulated concept (Money, Address, etc.)

Anti-Patterns to Avoid

Solidify your understanding by recognizing these common anti-patterns that violate clean class design:

Class Design Anti-Patterns

•God Class — One class that does everything: validation, persistence, calculation, formatting, notification. Split by responsibility.
•Utility Dumping Ground — A Utils class where homeless functions accumulate. Extract focused classes: DateParser, UrlBuilder, StringFormatter.
•Data Class — A class that's just fields with getters/setters and no behavior. Move behavior from clients into the class (Rich Domain Model).
•Feature Envy — Methods that use another object's data more than their own. Move the method to where the data lives.
•Middle Man — A class whose methods all delegate to another class. Remove the middleman or merge the classes.
•Primitive Obsession — Using String, int, boolean for domain concepts. Introduce value objects: EmailAddress, PhoneNumber, Money.
•Parallel Inheritance Hierarchies — Two hierarchies that always change together. Consider merging or using composition.
•Lazy Class — A class that doesn't do enough to justify its existence. Inline it into its clients.

The Path to Mastery

Understanding these principles is the first step; mastery comes through deliberate practice. Here's how to internalize clean class design:

Practice Recommendations

•Review Your Own Code — Apply the checklist to classes you wrote last month. What would you change now?
•Study Good Examples — Read source code of well-maintained open source projects. Notice how classes are sized and named.
•Pair on Refactoring — Work with a colleague to refactor a problematic class. Discuss trade-offs aloud.
•Practice Katas — Implement classic OOP problems (Bowling Game, Mars Rover) with focus on clean class design.
•Lead Reviews — Volunteer to review others' code with an eye on class design. Teaching reinforces learning.
•Measure Progress — Track metrics on your projects over time. Are class sizes decreasing? Is cohesion improving?

The Progression

At first, you'll apply the checklist consciously, item by item. Over time, it becomes intuition—you'll feel when a class is getting too large or when a name doesn't quite fit. Trust the process. The checklist becomes instinct.

Module Summary: Designing Clean Classes

This module has equipped you with the principles and practical tools for designing classes that are maintainable, understandable, and professional-grade.

Module Takeaways

•Single Purpose — Each class should have exactly one reason to change, serving one stakeholder.
•Meaningful Names — Names should predict behavior, use domain vocabulary, and avoid generic suffixes.
•Appropriate Size — Classes should fit in working memory, neither too large (god class) nor too small (over-decomposition).
•Cohesive Members — Every field and method should work together toward the class's single purpose.
•Use the Checklist — Apply systematic evaluation to every class you design, write, or review.
•Refactor Fearlessly — When design problems emerge, refactoring techniques exist to fix them. Don't accept poor design.
•Practice Deliberately — Mastery comes from repeated, conscious application of these principles.

What's ahead:

With classes mastered, the next chapter explores Encapsulation—protecting data and behavior, hiding implementation details, and exposing only what's necessary. Encapsulation is the guardian of clean class design, ensuring that your well-designed classes remain well-designed as systems evolve.

Module Complete

Congratulations! You've completed Module 7: Designing Clean Classes. You now possess a comprehensive understanding of what makes a class well-designed and a practical checklist to apply this knowledge consistently. May all your classes be single-purpose, well-named, appropriately-sized, and highly cohesive!