Ask HN: Best codebases to study to learn software design?

My suggestion is to search for open-source codebases in your favorite languages, study them, and start practicing them.

While studying well-designed codebases is incredibly valuable, there's an important "tip of the iceberg" effect to consider: much of good software design lives in the "negative space" - what's deliberately not there.

The decisions to exclude complexity, avoid premature abstractions, or reject certain patterns are often just as valuable as the code you can see. But when you're studying a codebase, you're essentially seeing the final edit without the editor's notes - all the architectural reasoning that shaped those choices is invisible.

This is why I've started maintaining Architectural Decision Records (ADRs) in my projects. These document the "why" behind significant technical choices, including the alternatives we considered and rejected. They're like technical blog posts explaining the complex decisions that led to the clean, simple code you see.

ADRs serve as pointers not just for future human maintainers, but also for AI tools when you're using them to help with coding. They provide readable context about architectural constraints and compromises - "we've agreed not to do X because of Y, so please adhere to Z instead." This makes AI assistance much more effective at respecting your design decisions rather than suggesting patterns you've deliberately avoided.

When studying codebases for design patterns, I'd recommend looking for projects that also maintain ADRs, design docs, or similar decision artifacts. The combination of clean code plus the architectural reasoning behind it - especially the restraint decisions - provides a much richer learning experience.

Some projects with good documentation of their design decisions include Rust's RFCs, Python's PEPs, or any project following the ADR pattern. Often the reasoning about what not to build is more instructive than the implementation itself.

I'm definitely going to do that. I asked because I wanted to start off with some that I'd knew would be well designed. However, it would probably be more interesting to see a wide variety of quality than just the good ones.

Or maybe open source projects are all usually well designed. I haven't looked at many in depth. The only one I've really looked into was Clang to try to figure out why clang format ignored my style rules when styling files of certain names. (Turns out there is a list of file names that automatically are considered Objective-C rather than C++)

Oooh I like that idea. I may steal it. I'll be on the lookout for documents like that. It'll be interesting to see what patterns/designs were avoided. There are so many ways to accomplish the same thing it might be nice to set some limits.