Encapsulating Complexity

# Encapsulating Complexity

## Overview

Hide HOW things work. Expose only WHAT they do. Work at domain level (Users, Orders, Config), not implementation level (dicts, SQL rows, JSON files).

**Core principle:** The point of encapsulation is to create possibilities (many ways to implement) and restrict possibilities (one way to use). Implementation details hidden = free to change implementation without breaking clients.

**Violating the letter of this rule is violating the spirit of information hiding.**

## When to Use

**Apply to every class and interface:**
- Designing new classes/modules
- Creating public APIs
- Reviewing code for abstraction leaks
- Refactoring to improve maintainability

**Warning signs you're violating encapsulation:**
- Client code knows storage format (JSON, SQL, files)
- Interface exposes database/file operations
- Returns raw dicts/rows instead of domain objects
- Client code constructs SQL queries or file paths
- Changing from JSON to YAML breaks client code
- Switching databases requires changing all callers
- Tests must know internal data structures
- Method names reveal implementation (saveToJSON, queryDatabase)
- Public fields exposing internal state

## The Encapsulation Test

**Ask these questions about every public method/field:**

1. **Does the interface expose HOW or WHAT?**
   - "Get user" = WHAT (good)
   - "SELECT * FROM users" = HOW (bad)

2. **Can I change implementation without breaking clients?**
   - JSON → YAML: should work
   - PostgreSQL → MongoDB: should work
   - If clients break: encapsulation violated

3. **Do clients work at domain level or implementation level?**
   - Domain: `user.email`, `config.get_timeout()`
   - Implementation: `row[2]`, `json_data['timeout_ms']`

4. **Do return values expose internals?**
   - Domain: `User` object
   - Implementation: `dict` with database column names

**If answers reveal implementation details → encapsulation violated.**

## Core Pattern: Hide the How

### Before (Implementation Exposed)

```python
class ConfigManager:
    def __init__(self, json_path):
        self.json_path = json_path  # ❌ Exposes JSON
        self._data = {}

    def get_value(self, key):
        return self._data.get(key)  # ⚠️ Returns raw value

    def save_to_json(self):  # ❌ "JSON" in method name
        with open(self.json_path, 'w') as f:
            json.dump(self._data, f)
```

**Client code:**
```python
config = ConfigManager("/path/to/config.json")  # Must know it's JSON
timeout = config.get_value("timeout_ms")  # Must know exact key format
config.save_to_json()  # Tied to JSON format
```

**If you switch JSON → YAML:** Client code breaks. Method names wrong. Constructor signature wrong.

### After (Implementation Hidden)

```python
class Config:
    def __init__(self, config_file):  # ✅ No format specified
        self._storage = self._load(config_file)  # ✅ Implementation hidden

    def get_timeout(self):  # ✅ Domain method, not raw key access
        return self._storage.get("timeout_ms", 5000)

    def set_timeout(self, seconds):  # ✅ Domain operation
        self._storage["timeout_ms"] = seconds * 1000  # ms internally

    def save(self):  # ✅ No "JSON" in name
        self._persist(self._storage)

    def _load(self, config_file):  # ✅ Private - can change format
        # Could