Software Design Principles

# ❌ Bad: Multiple responsibilities -- this class changes when the database
# schema changes AND when the email provider changes. Two unrelated teams
# (backend + communications) would both need to modify this file.
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
    
    def save_to_database(self):
        # Database logic -- changes when schema/ORM changes
        pass
    
    def send_email(self):
        # Email logic -- changes when email provider changes
        pass

# ✅ Good: Single responsibility -- each class has exactly one reason to change.
# If you switch from PostgreSQL to MongoDB, only UserRepository changes.
# If you switch from SendGrid to Mailgun, only EmailService changes.
class User:
    """Pure data + business rules. No I/O, no side effects."""
    def __init__(self, name, email):
        self.name = name
        self.email = email

class UserRepository:
    """Knows HOW to persist users. One reason to change: storage concerns."""
    def save(self, user):
        pass

class EmailService:
    """Knows HOW to send emails. One reason to change: communication concerns."""
    def send(self, user, message):
        pass

# ❌ Bad: Must modify class for new shapes
class AreaCalculator:
    def calculate(self, shape):
        if shape.type == "circle":
            return 3.14 * shape.radius ** 2
        elif shape.type == "rectangle":
            return shape.width * shape.height
        # Must add more elif for each shape!

# ✅ Good: Extend without modifying
from abc import ABC, abstractmethod

class Shape(ABC):
    @abstractmethod
    def area(self):
        pass

class Circle(Shape):
    def __init__(self, radius):
        self.radius = radius
    
    def area(self):
        return 3.14 * self.radius ** 2

class Rectangle(Shape):
    def __init__(self, width, height):
        self.width = width
        self.height = height
    
    def area(self):
        return self.width * self.height

# New shapes just implement Shape interface
class Triangle(Shape):
    def __init__(self, base, height):
        self.base = base
        self.height = height
    
    def area(self):
        return 0.5 * self.base * self.height

# ❌ Bad: Square violates Rectangle's contract.
# Client code expects: "I set width to 5 and height to 10, so area = 50."
# But Square silently overrides height when you set width -- area = 25!
# The subclass breaks the behavioral contract of the parent class.
class Rectangle:
    def set_width(self, width):
        self.width = width
    
    def set_height(self, height):
        self.height = height

class Square(Rectangle):
    def set_width(self, width):
        self.width = width
        self.height = width  # Violates expectation! Caller did not ask for this.
    
    def set_height(self, height):
        self.width = height  # Same problem -- silent side effect.
        self.height = height

# ✅ Good: Separate abstractions
class Shape(ABC):
    @abstractmethod
    def area(self):
        pass

class Rectangle(Shape):
    def __init__(self, width, height):
        self.width = width
        self.height = height
    
    def area(self):
        return self.width * self.height

class Square(Shape):
    def __init__(self, side):
        self.side = side
    
    def area(self):
        return self.side ** 2

# ❌ Bad: Fat interface
class Worker(ABC):
    @abstractmethod
    def work(self):
        pass
    
    @abstractmethod
    def eat(self):
        pass
    
    @abstractmethod
    def sleep(self):
        pass

class Robot(Worker):
    def work(self):
        print("Working...")
    
    def eat(self):
        pass  # Robots don't eat!
    
    def sleep(self):
        pass  # Robots don't sleep!

# ✅ Good: Segregated interfaces
class Workable(ABC):
    @abstractmethod
    def work(self):
        pass

class Eatable(ABC):
    @abstractmethod
    def eat(self):
        pass

class Human(Workable, Eatable):
    def work(self):
        print("Working...")
    
    def eat(self):
        print("Eating...")

class Robot(Workable):
    def work(self):
        print("Working...")

# ❌ Bad: High-level depends on low-level -- UserService is welded to MySQL.
# Cannot test without a real MySQL instance. Cannot switch to PostgreSQL
# without rewriting UserService. Cannot use a different database in staging.
class MySQLDatabase:
    def save(self, data):
        print("Saving to MySQL...")

class UserService:
    def __init__(self):
        self.db = MySQLDatabase()  # Hardcoded! This is the coupling problem.
    
    def create_user(self, user):
        self.db.save(user)

# ✅ Good: Both depend on abstraction -- the "inversion" is that MySQLDatabase
# now conforms to an interface defined by the needs of UserService, not the
# other way around. UserService defines WHAT it needs; the adapter provides HOW.
class Database(ABC):
    @abstractmethod
    def save(self, data):
        pass

class MySQLDatabase(Database):
    def save(self, data):
        print("Saving to MySQL...")

class PostgreSQLDatabase(Database):
    def save(self, data):
        print("Saving to PostgreSQL...")

class UserService:
    def __init__(self, db: Database):  # Inject the abstraction, not a concrete class
        self.db = db
    
    def create_user(self, user):
        self.db.save(user)

# Usage -- swap implementations with zero changes to UserService.
# In tests, inject a FakeDatabase that stores data in a dict.
mysql_service = UserService(MySQLDatabase())
postgres_service = UserService(PostgreSQLDatabase())
test_service = UserService(FakeDatabase())  # Fast, in-memory tests

# ❌ Bad: Repeated KNOWLEDGE -- the bonus formula appears in two places.
# If the bonus percentage changes from 10% to 12%, you must find and
# update both functions. Miss one and you have an inconsistent system.
def calculate_employee_bonus(employee):
    base_salary = employee.salary
    years = employee.years_of_service
    bonus = base_salary * 0.1 * years
    return bonus

def calculate_manager_bonus(manager):
    base_salary = manager.salary
    years = manager.years_of_service
    bonus = base_salary * 0.1 * years  # Same formula! Same business rule!
    bonus += 5000  # Manager extra
    return bonus

# ✅ Good: Single source of truth for the base bonus formula.
# Change the formula in one place, all callers get the update.
def calculate_base_bonus(person):
    return person.salary * 0.1 * person.years_of_service

def calculate_employee_bonus(employee):
    return calculate_base_bonus(employee)

def calculate_manager_bonus(manager):
    return calculate_base_bonus(manager) + 5000

# ❌ Over-engineered -- a Factory pattern for reversing a string!?
# This is 8 lines of code to do what 1 line does. Every abstraction
# layer is a tax on readability. Pay that tax only when it buys you
# flexibility you actually need.
class StringReverserFactory:
    def create_reverser(self):
        return StringReverser()

class StringReverser:
    def reverse(self, s):
        return ''.join(reversed(list(s)))

# ✅ Simple -- one function, one line, zero indirection.
# The next developer who reads this code wastes zero mental cycles.
def reverse_string(s):
    return s[::-1]

# ❌ Bad: Building for hypothetical future
class User:
    def __init__(self, name):
        self.name = name
        self.middle_name = None
        self.suffix = None
        self.nickname = None
        self.avatar_url = None
        self.theme_preference = None
        self.notification_settings = {}
        # 20 more fields "just in case"

# ✅ Good: Start minimal, add when needed
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email

# ❌ Bad: Deep inheritance hierarchy
class Animal:
    def move(self): pass

class Bird(Animal):
    def fly(self): pass

class Penguin(Bird):  # Problem: Penguins can't fly!
    def fly(self):
        raise Exception("Can't fly")

# ✅ Good: Composition with behaviors
class FlyBehavior:
    def fly(self):
        print("Flying!")

class WalkBehavior:
    def walk(self):
        print("Walking!")

class Bird:
    def __init__(self, fly_behavior=None, walk_behavior=None):
        self.fly_behavior = fly_behavior
        self.walk_behavior = walk_behavior

# Penguin walks but doesn't fly
penguin = Bird(walk_behavior=WalkBehavior())

# Eagle flies and walks
eagle = Bird(fly_behavior=FlyBehavior(), walk_behavior=WalkBehavior())

# ❌ Bad: Train wreck - reaching through objects
def get_city(order):
    return order.get_customer().get_address().get_city()

# ✅ Good: Ask, don't reach
class Order:
    def get_shipping_city(self):
        return self.customer.get_shipping_city()

class Customer:
    def get_shipping_city(self):
        return self.address.city

def get_city(order):
    return order.get_shipping_city()

# ❌ Deep nesting -- every level of indentation adds cognitive load.
# By the time you reach the actual work, you have mentally tracked
# four conditions. This is exhausting to read and easy to get wrong.
def process_order(order):
    if order:
        if order.is_valid():
            if order.has_items():
                if order.customer.has_credit():
                    # finally do something (the reader is exhausted)
                    pass

# ✅ Guard clauses (early return) -- reject bad cases upfront, then
# the remaining code runs at a single indentation level with zero
# cognitive overhead. The "happy path" reads like a straight line.
def process_order(order):
    if not order:
        return
    if not order.is_valid():
        raise InvalidOrderError()
    if not order.has_items():
        raise EmptyOrderError()
    if not order.customer.has_credit():
        raise InsufficientCreditError()
    
    # Clean path -- if you reach here, all preconditions are satisfied.
    # No nesting, no ambiguity about what state the data is in.
    process(order)