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.

Slides on SpeakerDeck.

(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)
• 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.
• What Color is Your Function?

  • 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.

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
  • Advent of Code
• Łukasz Langa’s Keynote PyCon US 2022
• 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.
• 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.