Maintaining Consistent Abstractions

# 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:**
```python
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:**
```python
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:**
```python
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

    de