Cohesion, coupling and the SOLID principles

Lesson 1 named cohesion and coupling as the two forces behind code that is easy or hard to change. This lesson looks at them closely and then at SOLID, five principles that Robert C. Martin gathered in the early 2000s to help object-oriented code stay cohesive and loosely coupled. The principles were written with languages such as Java and C++ in mind, so this lesson also shows what each one looks like in Python, where functions are objects, duck typing replaces many interfaces, and a module is often the right unit of design.

Lena's review of the ridgeline package becomes the running example. She found a ReportPrinter class that fetched data, calculated totals and formatted output; a shipping function with an if-chain for every carrier; a GiftCard class that pretended to be a physical product; and an order service that created its own database connection. Each problem maps onto one of the principles.

Cohesion: things that change together belong together

Cohesion describes how strongly the parts of a module, class or function are related. The classic scale runs from coincidental cohesion, where parts are grouped for no reason (a utils.py full of unrelated helpers), through logical cohesion, where parts do similar kinds of things (all the input readers in one place), to functional cohesion, where every part contributes to one well-defined task (a money module that parses, rounds and formats amounts).

A practical test is to describe what the piece does in one sentence without using the word and. The money module rounds and formats amounts of money for display, which is one job described from two angles. ReportPrinter loads sales from the database and computes totals and formats a report, which is three jobs. Another test is to ask who would ask for a change: if the accountant, the database administrator and the web designer could each ask for a change to the same class, it has low cohesion.

Coupling: how much pieces know about each other

Coupling describes how much one piece depends on another. Some coupling is necessary, because pieces must work together, but some kinds are far more expensive than others. From tightest to loosest, the traditional list runs: content coupling, where one module reaches into another's private data; common coupling, where modules share global variables; control coupling, where one passes a flag that tells the other what to do; stamp coupling, where a whole record is passed when only one field is needed; and data coupling, where only the simple values that are needed are passed.

In Python, the most common sources of tight coupling are module-level global state, reaching into another object's underscore attributes, long chains such as order.customer.address.city.lower() that depend on the structure of four classes, and boolean flag parameters such as print_report(data, as_html=True), which make the caller control the callee's internal branching.

# Tight: the caller must know the internal layout of Order and Customer.
def label_tight(order):
    return f"{order['customer']['address']['city'].upper()} #{order['id']}"

# Looser: the order offers what callers need; callers stop depending on its structure.
class Order:
    def __init__(self, order_id, city):
        self.id = order_id
        self._city = city

    def ship_to_city(self):
        return self._city.upper()

def label_loose(order):
    return f"{order.ship_to_city()} #{order.id}"

print(label_tight({"id": 1041, "customer": {"address": {"city": "Kelowna"}}}))
print(label_loose(Order(1041, "Kelowna")))

KELOWNA #1041
KELOWNA #1041

The second version follows the Law of Demeter, sometimes stated as talk to friends, not strangers: a function should call methods on its own objects and parameters, not on objects it reached through them. If the way addresses are stored changes, only Order changes, not every label, invoice and report that needs a city.

S: the single responsibility principle

The single responsibility principle says a module or class should have one reason to change, or in Martin's later wording, should be responsible to one actor: one person or group whose requests drive changes to it. It is cohesion stated as a rule. ReportPrinter breaks it, because the accountant (totals), the database administrator (queries) and the web designer (formatting) all drive changes to it.

The fix is to split along the lines of those reasons: a SalesSource that loads records, a function that computes the summary, and a formatter that turns a summary into text. Each piece is now small enough to test on its own, and the formatter can be swapped for an HTML or CSV formatter without touching the arithmetic.

def report(sales):
    bags = 0
    revenue = 0
    for sku, qty, price in sales:
        bags += qty
        revenue += qty * price
    return f"Bags: {bags} | Revenue: {revenue:.2f}"

print(report([("RC-101", 2, 18.50), ("RC-104", 1, 20.25)]))

O: the open-closed principle

The open-closed principle, from Bertrand Meyer, says software should be open for extension but closed for modification: you should be able to add new behavior by adding new code, without editing code that already works. Ridgeline's shipping function was the opposite. Every new carrier meant opening the function and adding another elif, retesting all the existing branches, and hoping nothing broke.

In Python, the usual way to make code open for extension is a registry: a dictionary that maps a name to a function or class, plus a small decorator that adds entries to it. The core code looks things up in the registry and never needs to change; a new carrier is a new function with one decorator line. Lesson 6 calls this the strategy pattern, and lesson 7 returns to registries as a plugin system.

SHIPPERS = {}

def shipper(name):
    def register(func):
        SHIPPERS[name] = func
        return func
    return register

@shipper("pickup")
def pickup(weight_kg):
    return 0.0

@shipper("canada_post")
def canada_post(weight_kg):
    return round(9.50 + 2.25 * weight_kg, 2)

def shipping_cost(method, weight_kg):
    try:
        return SHIPPERS[method](weight_kg)
    except KeyError:
        raise ValueError(f"unknown shipping method: {method}") from None

# Adding a carrier later needs no change to shipping_cost:
@shipper("courier")
def courier(weight_kg):
    return 15.0 if weight_kg <= 5 else 22.0

for m in ["pickup", "canada_post", "courier"]:
    print(m, shipping_cost(m, 2.0))

pickup 0.0
canada_post 14.0
courier 15.0

def bike(weight_kg):
    return 6.0

print(shipping_cost("pickup", 2))

L: the Liskov substitution principle

Barbara Liskov's substitution principle says that objects of a subclass must be usable anywhere objects of the parent class are expected, without the caller noticing. A subclass may add behavior, but it must keep the parent's promises: accept at least the same inputs, return the same kinds of results, and not raise new exceptions for operations the parent supports.

In the ridgeline package, Product had a shipping_weight() method, and GiftCard inherited from Product. Gift cards are emailed, so the developer made GiftCard.shipping_weight() raise NotImplementedError. Every function that loops over products and adds up weights now crashes when a basket contains a gift card. The subclass broke the parent's promise. The fix is to keep the promise (a gift card weighs 0 kg and ships digitally) or, if the promise genuinely does not apply, to stop pretending: model gift cards as a separate kind of item that does not inherit shipping behavior at all.

Duck typing does not remove Liskov's principle; it widens it. Any object passed where code expects something with a shipping_weight() method should honor the same contract, whether or not it inherits from Product.

I: the interface segregation principle

The interface segregation principle says that clients should not be forced to depend on methods they do not use. In languages with formal interfaces, a fat interface with fifteen methods forces every implementer to provide all fifteen, even when a client needs only two. In Python, the equivalent problem is a function that demands a rich object when it only needs one capability, or an abstract base class that requires many methods from every subclass.

The Pythonic answer is small protocols. A function that prints shelf labels needs only something with a name and a price; it should accept any such object, not demand an entire Coffee with stock levels and roast dates. Lesson 7 shows how typing.Protocol expresses these small interfaces explicitly, so type checkers can verify them without forcing inheritance.

D: the dependency inversion principle

The dependency inversion principle says that high-level policy should not depend on low-level details; both should depend on abstractions. Ridgeline's order service created its own SQLite connection inside its constructor and called it directly. That made the business rules (high level) depend on the database (low level): the service could not be tested without a real database, and moving to PostgreSQL meant editing business code.

Inverting the dependency means the service asks for what it needs, something that can save and load orders, and the caller supplies it. In production, the caller passes a SQLite repository; in tests, an in-memory one; later, a PostgreSQL one. This is dependency injection, and in Python it is usually nothing more than passing an object to the constructor.

class InMemoryOrders:
    """Satisfies the same contract as the SQLite repository: add() and all()."""
    def __init__(self):
        self._orders = []

    def add(self, order):
        self._orders.append(order)

    def all(self):
        return list(self._orders)

class OrderService:
    def __init__(self, orders):          # the dependency is passed in, not created here
        self.orders = orders

    def place(self, customer, total):
        order = {"customer": customer, "total": total}
        self.orders.add(order)
        return order

service = OrderService(InMemoryOrders())
service.place("Alder Hotel", 204.0)
service.place("Bayside Bakery", 121.5)
print(len(service.orders.all()), "orders stored")

2 orders stored

from datetime import date

def is_stale(roast_date):
    return (date.today() - roast_date).days > 30

print(is_stale(date(2020, 1, 1)))