Code Smell 47 - Diagrams

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

Problems

• Maintainability

• Trash code

• Code Duplication

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

Solutions

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

Wrong

Right

	<?
	final class BookItem {
	function numberOfPages() { }
	function language(): Language { }
	function book(): Book { }
	function edition(): BookEdition { }
	// Loan and overdues are not book items responsibility
	}
	final class LoanTracker {
	function loan(
	BookItem $bookCopy,
	LibraryUser $reader,
	DatePeriod $loanDates) {
	// DatePeriod is better than anemic $fromDate and $toDate
	}
	}
	final class LoanTrackerTests extends TestCase {
	// Lots of maintained tests telling you how the system really works
	}

view raw library.php hosted with ❤ by GitHub

Detection

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

Examples

• Automatic Code Generators

Conclusion

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.

Relations

Code Smell 01 - Anemic Models

Maxi Contieri ・ Oct 20 '20

#codenewbie #oop #beginners #computerscience

Code Smell 25 - Pattern Abusers

Maxi Contieri ・ Nov 15 '20

#oop #tutorial #programming #patterns

More info

Code Wizards

CASE

DDD

Credits

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

Comments

[𒎏Wii 🏳️‍⚧️]

UML is a joke. It's the attempt of people who don't like programming to avoid it and do code-free software engineering. The problem is that this ultimately just removes the main difficulty of figuring out the implementation details and creates a world of make-believe where programs don't need to actually compile or execute.

The obvious exception is, of course, when discussing different implementation approaches, as a short-term thing, but not as documentation.

As you pointed out, most of these diagrams express how something is implemented (structure), not its behaviour. I hadn't considered it from this perspective yet, but you're definitely right. A good diagram would express primarily what code does, not how it does it. However, some diagrams manage to convey at least a bit of behaviour as well, but even then writing a simple markdown document can do a much better job.

Trust your tests. They are alive and well maintained.

Maybe one could use diagrams to describe these tests. At least on the surface this seems like it could work.