By Marcus Biel, Clean Code Academy

Jax direct link

Defining a clean architecture

Should be simple top-down.

Sadly, often real world complexity knocks on the door, and the sketch isn’t very clean after all.

Hide the truth? NO!

Build systems with modules

Hexagonal architecural pattern

Split architecture in infrastructure and domain.

Infrastructure layer is responsible for communication etc.

Head First Domain-Driven Design

Enforce layering with Java Modules.

Building blocks of a clean architecture

  • Size
  • Naming
  • Encapsulation
  • Coupling and cohesion

Size matters

Smaller is better – shy away from complexity.

Guideline upper limit for each of

  • modules
  • packages
  • classes
  • methods

Know when you violate this and reflect on it.


  • clean names drive high cohesion (Customer, AccountNumber)
  • use service pattern judiciously
  • clean names are team work
  • rename on new insights

A good name groks the purpose.

Understand the goal of your business!


  • technically enforces of how the system should be used
  • getters and settes violate encapsulation
  • use package private more often!

Coupling and cohesion

Coupling: Avoid N:N, prefer clean dependency chains.

Prefer lower coupling farther out in the layers of your architecture.

Cohesion: ”single responsibility principle”. Låt lika leka med lika == high cohesion.

High cohesion requires in-depth knowledge of the domain.