Code Smell 47 - Diagrams

Subscribe to my newsletter and never miss my upcoming articles

Diagrams are not code. They cannot be a code smell. They are just Diagram Smells.


  • Maintainability

  • Trash code

  • Code Duplication

  • Diagrams focus only on structure (accidental) and not behavior (essential).


  1. Use diagrams only to communicate ideas with other humans.

  2. Program on your favorite IDE.

  3. Thrash all diagrams. Even the ones generated from the source code.

  4. Trust your tests. They are alive and well maintained.

  5. Use Domain Driven Design technique.

Sample Code




We can remove all code annotations and forbid them by policy.



Designing is a contact sport. We need to prototype and learn from our running models.

Papers and JPGs don't run. They live in the utopic world where everything works smoothly.

CASE was a very hot trend back in the 90s. No good system was developed with these tools.


More info


Photo by Nick Seagrave on Unsplash

The Diagram is Not the Model. The model is not the diagram. It is an abstraction, a set of concepts and relationships between them.

Eric Evans

This article is part of the CodeSmell Series.

Comments (2)

Chris Bongers's photo

I tend to disagree, we still use diagrams and functional designs to help understand the semi/non-technical client what we are building.

It's a decent way to validate if what we are going to build is what they envisioned.

We rather spend the hour making the diagram and functional designs than building something only to realize it's not what they wanted.

Maxi Contieri's photo

Sure !

But you use diagrams to talk to other humans. That's a very valid scenario.

I prefer to validate what user wants using TDD.

The main problem with diagrams is that you discuss DATA with users. And data is accidental. You need to discuss behavior with them. And, IMHO, functional tests and acceptance tests are better for it.

We can validate rapid prototyping and validations with diagrams or Acceptance tests. I prefer the latter.