apply-unix-philosophy

Apply Unix Philosophy

Build components that do one thing well and connect to others through clean, standard interfaces.

Why This Is Best Practice

Adopted by: Unix/Linux operating system (foundational design since 1970s); Go toolchain (each go subcommand is a focused tool); Docker/container ecosystem (one process per container); AWS Lambda (single handler function per event); Kubernetes (single-purpose controllers). The Unix philosophy is the design principle behind every successful composable platform. Impact: McIlroy's original formulation — "Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams" — became the model for how 60+ years of Unix tools remained independently useful while combining into arbitrarily complex pipelines. A study of Unix tool longevity vs. monolithic application platforms shows tools following this philosophy (awk, sed, grep, curl) are still in active use decades later; monolithic alternatives have been replaced multiple times. Why best: The competing approach — a component that accumulates features over time — optimizes for short-term convenience at the cost of long-term reusability. When a component does two things, you cannot use it in contexts where only one is needed. When a component does ten things, it can only be used by callers who accept all ten. The Unix philosophy is the only design approach with a 60-year track record of producing reusable, replaceable software components.

Sources: McIlroy, Pinson & Tague, "UNIX Time-Sharing System: Forward" (Bell Labs, 1978); Raymond, "The Art of Unix Programming" (Addison-Wesley, 2003); Dan North, "CUPID—for joyful coding" (2022)

Status: Emerging — the Unix philosophy itself is proven; its framing as a CUPID property by Dan North (2022) is gaining traction but not yet majority-adopted under this label.

Steps

1. Define one clear purpose

Before writing a line of code, state what the component does in a single sentence with a single verb and no conjunctions.

• "Validates a payment amount" ✓
• "Authenticates the user and logs the attempt and sends a notification" ✗ — three things
• "Converts a CSV row to a domain object" ✓

If you cannot write this sentence, the scope is not yet clear. Clarify before building.

---

2. Connect through standard interfaces

A component that speaks a standard language (HTTP, stdin/stdout, files, queues) can be combined with anything. A component with a bespoke integration protocol can only be combined with what was designed alongside it.

• CLIs: read from stdin, write to stdout, use exit codes for errors
• Services: use HTTP or gRPC with standard status codes
• Libraries: accept and return domain types defined by an interface, not a concrete class
• Pipelines: each stage receives a value, transforms it, passes it on — no shared state between stages

# Bad — bespoke format, tied to this ecosystem
my-tool --input-json '{"records": [...]}' --output-db postgres://...

# Good — standard streams; composes with any Unix tool
cat records.csv | my-tool | psql -c "COPY table FROM STDIN"

---

3. Separate concerns at the integration point

When two concerns appear in one component, find the interface between them and extract it.

Signal: a change to feature A breaks feature B. Signal: testing feature A requires setting up feature B's state.

# Bad — fetching and processing fused; can't test processing without HTTP
def get_and_process_orders(user_id):
    response = requests.get(f"/api/users/{user_id}/orders")
    orders = response.json()
    return [o for o in orders if o["status"] == "pending"]

# Good — separated; each function has one purpose
def fetch_orders(user_id) -> list[dict]:
    return requests.get(f"/api/users/{user_id}/orders").json()

def filter_pending(orders: list[dict]) -> list[dict]:
    return [o for o in orders if o["status"] == "pending"]

# Caller composes them
pending = filter_pending(fetch_orders(user_id))

---

4. Resist feature accretion

The strongest pressure against the Unix philosophy is convenience: "while we're here, let's also handle X." Each addition makes the component slightly less reusable.

Apply the single-purpose test before every feature addition:

• "Does this belong in this component, or does it belong in a new component that calls this one?"
• If in doubt: new component. Adding is cheap; removing a responsibility that callers depend on is expensive.

---

5. Test each component in isolation

If a component truly does one thing, you can test it with no external setup. If setup requires mocking three other systems, the component is doing more than one thing.

// Bad — handler mixes auth, business logic, and persistence; test needs all three
func HandleCreateOrder(w http.ResponseWriter, r *http.Request) {
    user := auth.GetCurrentUser(r)          // auth concern
    order := parseOrder(r.Body)             // parsing concern
    db.Save(order)                          // persistence concern
    notify.SendConfirmation(user, order)    // notification concern
}

// Good — each concern is a function with one clear input/output; each is testable alone
func ParseOrder(body io.Reader) (Order, error) { ... }
func ValidateOrder(o Order) error { ... }
func SaveOrder(store OrderStore, o Order) error { ... }

Common Mistakes

Confusing "one thing" with "one line." A single purpose can involve multiple steps. validate-payment can check amount, currency, and card presence — all in service of one goal. The test is not "how many operations" but "how many reasons would this change?"

Splitting too fine. A two-line utility function does not need to be a separate service. The Unix philosophy applies at the level where independent reuse and independent replacement are meaningful. Micro-splitting functions produces noise, not clarity.

Bespoke interfaces. A component that does one thing but requires a custom protocol to call it is not Unix-philosophy-compliant — it can only be combined with what knows its protocol. Standard interfaces are the other half of the principle.

When NOT to Use

• User-facing features that are conceptually atomic — a "checkout" flow that validates, charges, and confirms is one user action; splitting it into three separate APIs may serve no consumer
• Performance-critical pipelines — function call overhead matters in tight loops; fused operations can outperform composed ones measurably
• Framework handlers — HTTP frameworks, job runners, and event systems often require a single handler that manages the full request lifecycle; work within the framework's model