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)

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:

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)

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 load JSON, YAML, TOML, etc.
        pass

    def _persist(self, data):  # ✅ Private - implementation detail
        # Format hidden from clients
        pass

Client code:

config = Config("app.config")  # Format agnostic
timeout = config.get_timeout()  # Domain method (seconds)
config.set_timeout(10)
config.save()

Switch JSON → YAML: Client code unchanged. Just change _load() and _persist().

Domain Level vs Implementation Level

Work at the problem domain, not the solution domain:

Example 1: User Management

❌ Implementation Level:

class UserManager:
    def get_user_row(self, user_id):

…