Overcomplicating with Unnecessary Abstractions

Unnecessary abstraction is an anti-pattern because it adds indirection before the code has earned it. In Clojure, this often appears as extra protocols, multimethods, macros, wrappers, or tiny internal DSLs introduced to make the design feel elegant. Instead of making the system clearer, these layers hide behavior behind names that sound general but explain very little.

The core problem is not abstraction itself. The problem is abstraction that arrives earlier than the actual variability, complexity, or reuse pressure that would justify it.

Anti-Pattern: Solving Future Problems Before Present Ones

One of the most common forms is speculative architecture:

• a protocol with one implementation
• a multimethod for three closed cases
• a macro for logic a function could already express
• a “pluggable” layer nobody actually plugs into

This feels prudent because it seems to prepare the codebase for growth. In practice it often means:

• more files to navigate
• weaker call-site readability
• harder debugging
• more ways for design drift to accumulate

The anti-pattern is designing around hypothetical change instead of observed change.

Anti-Pattern: Wrapping Simple Data in Ceremony

Clojure is strong at expressing behavior directly with data and small functions. Unnecessary abstraction often appears when ordinary data shapes are wrapped in layers of constructors, dispatch helpers, and protocol surfaces that do not add real meaning.

Weak:

1(defprotocol UserLookup
2  (fetch-user [this id]))
3
4(defrecord UserLookupService [db]
5  UserLookup
6  (fetch-user [_ id]
7    (jdbc/execute-one! db ...)))

If the codebase has one implementation and no meaningful polymorphic pressure, a plain function is often clearer:

1(defn fetch-user [db id]
2  (jdbc/execute-one! db ...))

The abstraction layer is only worth keeping if it makes the system easier to understand or extend in a real way.

Anti-Pattern: Tiny DSLs for Ordinary Logic

Some teams start building little internal languages whenever repeated patterns appear. In Clojure this often happens with:

• macros
• maps interpreted by custom runners
• layered config structures that duplicate existing language constructs

Sometimes these are useful. Often they hide basic business logic behind a clever execution model that few readers fully understand.

If a domain-specific layer requires constant explanation, the abstraction may be extracting complexity from the call site while concentrating it into a smaller but more dangerous area.

Anti-Pattern: One More Layer Between Callers and Work

Another abstraction smell is the “relay race” architecture:

• route calls service
• service calls manager
• manager calls handler
• handler calls adapter
• adapter calls repo

Each layer may do almost nothing besides renaming the call.

This hurts because:

• stack traces get longer without becoming more informative
• readers must traverse more files to find the real behavior
• changes ripple across more surface area than necessary

Abstraction should compress complexity, not lengthen the path to it.

Anti-Pattern: Mistaking Reuse for Generalization

Developers often notice two similar call sites and immediately generalize them into a shared abstraction. That is sometimes correct, but it is also a common trap.

Two similar pieces of code may differ in ways that matter later. If generalized too early, the new abstraction becomes:

• hard to name honestly
• full of option flags
• burdened by edge cases
• harder to change than the original duplication

In Clojure, small local duplication is often cheaper than a premature generic layer.

Anti-Pattern: Over-Explaining the Language to Itself

Clojure already gives you:

• higher-order functions
• immutable data structures
• maps as lightweight records
• good collection abstractions
• functions as values

An anti-pattern appears when the code starts rebuilding these capabilities inside the application. Instead of leaning on the language, the system creates an application-specific framework that imitates it.

This is closely related to the inner platform effect, but at a smaller scale it often looks like “micro-frameworking” ordinary application code.

A Better Abstraction Decision Model

    flowchart TD
	    A["See repeated or similar code"] --> B{"Is the current version already hard to understand or change?"}
	    B -->|No| C["Leave it simple for now"]
	    B -->|Yes| D{"Is the variability real and stable?"}
	    D -->|No| E["Refactor locally, avoid generalization"]
	    D -->|Yes| F["Introduce the smallest abstraction that clarifies the design"]

This model is helpful because it treats abstraction as an earned move, not a reflex.

What to Do Instead

• start with the clearest direct solution
• wait for real variation before introducing general-purpose layers
• prefer functions and data to heavier mechanisms unless syntax or dispatch really demands more
• keep abstraction names honest about responsibility
• delete or collapse layers that no longer pay for themselves

Common Mistakes

• adding protocols or multimethods with only one real implementation
• building tiny DSLs for behavior that plain data and functions already express
• introducing wrappers that only forward calls
• generalizing duplicated code before its differences are understood
• mistaking “more reusable” for “more maintainable”

Key Takeaways

• Abstraction is valuable only when it reduces real complexity.
• Clojure already provides many flexible building blocks; do not rebuild them casually.
• Small, direct code is often the right starting point.
• Generalization should follow evidence, not anxiety about the future.
• If an abstraction is hard to explain, it may not be helping.

Ready to Test Your Knowledge?