Maintaining Consistent Abstractions

Overview

A class interface should present ONE cohesive abstraction. All methods should work toward a consistent purpose at a consistent level.

Core principle: Each class implements one Abstract Data Type (ADT). If you can't identify what ADT the class implements, it has poor abstraction.

Goal: Anyone using the class should see a clear, consistent set of related operations, not a miscellaneous grab-bag.

When to Use

Apply when designing any class:

• New class design
• Reviewing existing classes
• Refactoring
• API design

Warning signs of poor abstraction:

• Class groups unrelated functions
• Methods at different abstraction levels (high-level + low-level mixed)
• Domain object with serialization methods (to_json, to_xml)
• Business logic mixed with persistence (SQL in domain class)
• Temporal cohesion (things done at same time, not related by purpose)
• Can't clearly state what abstraction the class represents
• Class description has "and" connecting unrelated purposes

Abstraction Anti-Patterns from Baseline Testing

Anti-Pattern 1: Domain + Serialization Mixed

Baseline violation:

class Employee:
    def calculate_annual_salary(self):  # ✅ Domain operation
        return self.salary * 12

    def update_department(self, dept):  # ✅ Domain operation
        self.department = dept

    def to_json(self):  # ❌ Serialization detail
        return json.dumps({...})

    def get_details(self):  # ✅ Domain operation
        return {...}

Problem: Employee is a domain concept. JSON is a serialization format. Mixing these means:

• Employee must know about JSON, XML, Protobuf, etc.
• Changes to serialization format change Employee class
• Can't serialize same employee different ways

✅ Separate concerns:

class Employee:
    """Domain: Employee business logic only."""
    def __init__(self, name, employee_id, department, salary):
        self.name = name
        self.employee_id = employee_id
        self.department = department
        self.salary = salary

    def calculate_annual_salary(self):  # Domain
        return self.salary * 12

    def update_department(self, dept):  # Domain
        self.department = dept

# Separate serializer
class EmployeeSerializer:
    """Concern: Serialization formats."""
    @staticmethod
    def to_json(employee: Employee) -> str:
        return json.dumps({
            'name': employee.name,
            'id': employee.employee_id,
            ...
        })

    @staticmethod
    def to_xml(employee: Employee) -> str:
        # Can add XML without touching Employee
        pass

Now: Employee knows nothing about formats. Add CSV/XML/Protobuf without changing Employee.

Anti-Pattern 2: Miscellaneous Grab-Bag (Temporal Cohesion)

Baseline violation:

class Program:
    """Initialize application components."""
    def _init_database(self):  # Database concern
        pass

    def _setup_web_server(self):  # Web concern
        pass

    def _start_background_jobs(self):  # Jobs concern
        pass

    def _init_command_stack(self):  # Command concern
        pass

    def _init_report_formatter(self):  # Reports concern
        pass

Problem: These are unrelated functions grouped because they happen at startup (temporal cohesion). The class has no consistent abstraction - it's a miscellaneous collection.

Code Complete specifically calls this out as poor abstraction.

✅ Each subsystem initializes itself:

class DatabaseSystem:
    """Abstraction: Database operations."""
    def initialize(self):
        # Database-specific initialization
        pass

class WebServer:
    """Abstraction: Web serving."""
    def start(self):
        # Web server initialization
        pass

class BackgroundJobManager:
    """Abstraction: Job processing."""
    def start(self):
        # Job system initialization
        pass

# Coordinator stays high-level

…