Ever had this weird gut feeling that something is off in your code, but couldn’t put the finger on why? Are you starting your projects with the best intentions, following all best practices, and still feel like your architecture turns weird eventually?
So far, I’ve held it at PyCon US 2025 in Pittsburgh, USA.
(Sorry for the literal throat-cleaning in the video – I lost my voice the night before and worked on fumes and Fisherman’s Friends.)
Additional material
Some of the material was referred to directly in the talk but landed on the cutting floor due to time constraints.
They all are highly recommended reading/watching for the topic of software design writ large, though.
Articles
- Types of Coupling by Ben Orenstein
- Attractive nuisances in software design by Paul Ganssle
- Designing with types: Making illegal states unrepresentable by Scott Wlaschin
- The Vietnam of Computer Science by Ted Neward (spoiler: it’s ORMs)
- A summary by Jeff Atwood (Coding Horror)
- Many of the cited problems are solvable in modern ORMs, however the underlying tension of conflicting goals remains.
- Approximating Sum Types in Python with Pydantic by William Woodruff
- How I Build by Adam Montgomery
- DTOs & Mapping: The Good, the Bad, and the Excessive by Derek Comartin
- An example of a conscious decision process on when to map data and reinforcing my point that it’s a trade-off.
- The Typestate Pattern in Rust
by Cliff L. Biffle
- This is about Rust, but the concept applies the same to any other language.
- Writing Python like it’s Rust by Jakub Beránek
- Speaking of Rust! There is a new style of Python that emerged over the past years and I’m all-in.
- What Color is Your Function? by Bob Nystrom
This article argues against async primitives in languages because it causes you to have two different types of functions that behave differently. I don’t fully agree, but I find it interesting to apply this logic to classes.
Arguably, ORM classes and, to a much lesser degree, Pydantic classes, behave very differently than regular classes. Especially, because setting attributes implies I/O which complicates reasoning.
In other words, you have to be aware what kind (color!) of class you’re dealing with when reading code.
- Amundsen’s Maxim
Remember, when designing your Web API, your data model is not your object model is not your resource model is not your message model.
Videos
- Integrated Tests Are A Scam by J.B. Rainsberger
- The Deep Synergy Between Testability and Good Design by Michael Feathers
- SOLID Principles? Nope, just Coupling and Cohesion by Derek Comartin
- The Rising Sea by Matthew Drury
- Łukasz Langa’s PyCon US 2022 Keynote
- Simple Made Easy by Rich Hickey
- Watch it before you call anything “simple” ever again.
- Building Protocol Libraries The Right Way by Cory Benfield
- Introducing Sans I/O, which is a very related topic about writing I/O-agnostic network protocol libraries.
- Functional Core Imperative Shell by Gary Bernhardt
- What Gary calls Core, is business logic.
- Moving IO to the Edges of Your App: Functional Core, Imperative Shell by Scott Wlaschin
- Builds on Gary’s talk by misspelling his name and giving more concrete examples.
- Domain Modeling Made Functional by Scott Wlaschin
- Also available as a book.
Books
- Tidy First? by Kent Beck
- Very short and very good.
- Architecture Patterns With Python by Harry Percival and Bob Gregory
- I will recommend this book in every talk until I die.
- Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans
- This is a thicc, dense book that brings the whole domain modeling topic to its logical conclusion. It’s a great read for advanced developers, the DDD community feels sometimes a tad cultish, though.
Colophon & credits
- Postcard to Ireland
- Theodor Fontane
- Screenshot from 1923. Totally fair use; please don’t sue me.
- Get your Simpsons GIFs from Frinkiac
- “No Fate” GIF from Giphy which they pirated from the best SciFi movie ever.
