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

It's been asked a few times, here are some links to get you started:

* https://news.ycombinator.com/item?id=36370684

* https://news.ycombinator.com/item?id=30752540

* https://news.ycombinator.com/item?id=9896369 (Python specific)

I am not qualified enough to answer, but some ~15 years ago I enjoyed going through the book Code Reading[0], which is about this exact topic.

I think there was another one with a similar name but I can't think of it's name.

0: https://www.spinellis.gr/codereading/, check the TOC https://www.spinellis.gr/codereading/toc.html

These are several years old at this point, but many open source project leaders contributed to the series "The Architecture of Open Source Applications", which is free to read online: https://aosabook.org/en/index.html

UNIXv6 and the BSDs.

My experience (30 years in software, 25 in practicing architecture, MIT system architecture masters) tells me there is no such thing as abstractly “good” design. There are designs with negative consequences for sure, but “good” depends on the context: what are you building, safety/security requirements etc. Probably most importantly on the implementation team and it’s structure. A team of juniors will butcher your intricate design and Conway’s Law makes your software reflect the team.

Maybe I’m just not good enough at paying attention, but for me it seems like you have to actually run into problems over and over and figure out how to avoid the problems. Then you end up being able to mentally simulate what problems you will run into, and design is basically all about avoiding future problems of various kinds (and balancing tradeoffs about which future problems to avoid and how much effort to put into each, whether you can solve multiple with one design play, etc).

My immediate reaction to this question is: "your team's". Nothing will teach you more about how to design software then really understanding why good and bad solutions were adapted to solve a certain real problem.

Software exists precisely because there is still a messy layer connecting user requirements to actions on a computer. If there was not messiness then we could just automate it all. Approaching software from some sort of Platonic ideal of what software should be will frequently lead to bad decisions on it's own.

When you start to see how certain pressures lead to certain paths you learn to recognize the wrong decisions that are often good at the time, and avoid them. At the same time, you need to learn to develop methods that work quickly and effectively. By far the biggest real challenge in real world software is time constraints. This is almost never discussed in theoretical views of software, but the truth is you're always going to be writing code under pressure to ship. You will come across situations where you do not have time to do what you want to do or think is best.

Good software is software that runs and solves the user need, but you will come to realize that there are design solutions that will make successfully running happen more often. The best way to find these is to study the real software you're writing.

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

I can recommend reading about postfix architecture if you want to learn a bit about what would nowadays be called a microservice architecture:

https://www.postfix.org/OVERVIEW.html

You might need to know a bit about how email servers work to appreciate it though.

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'd recommend the book "Beautiful Code: Leading Programmers Explain How They Think". Published by O'Reilly, ISBN-10 ‏ : 0596510047

There's a free book on this topic: The Architecture of Open Source Applications

https://aosabook.org/en/index.html

Maybe that would be a good start. You can then pick a project to dive in.

As a more specific tip, I've done some hacks in Nginx long time ago and found it quite nice.

For website/web server learning I recommend the laravel code-base. It's a beauty.

https://www.instagram.com/reel/C2x4Ge5RtNC/

I dont think this is a good idea, actually. Good design is about making good trade offs at the right point in time.

A code base with excellent design will show you the end state but not how it got there but probably not the trade offs and decisions involved.

Practicing refactoring on subpar code bases and dealing with the consequences of your decisions is a better way to improve.

To answer your actual question:

The codebases I learned from the most are Git, Postgres, CPython. Not saying they are perfect designs, but they are well maintained, solve hard problems, have seen many years of evolution, and are very easy to get your hands on.

Your own. Everyone else's is trash. Never understand someone else's code-- the whole point is that there should be just a handful of functions of yours I can call, and shouldn't ever care to see how the sausage is made. Otherwise, your abstraction sucks

Trying to learn software design by looking at code is kind of like trying to learn about architecture looking at the bricks that make up a building.

To learn about design you need a wider perspective. You can theoretically learn it from code but it won’t be most effective. Look at great documentation and literature about design instead.

I think there is value in groking entire code bases. It's not just about whether or not they are well designed though. It is an important skill to be able to analyze and see the big picture of how things work together in large systems. For me it often involves drawing diagrams (sometimes UML) to map things out. Being able to view systems in this way is a pre-requisite to intentionally designing your own systems at this level. And yes, once you can work at this level you can learn from good designs, but also see problems with bad ones.

EDIT: and to answer your question, if you're working on something that is "like X but different" then read the source code for X. You could also look at source code for software that you use from day to day: software where you already know what it does. For example, if you're in web, maybe the web framework, or web server, if you write python, maybe a core library that you use, or maybe the python interpreter, or if you use vscode ..., if you use android ..., you get the idea. At the start I would suggest smaller programs, and programs where you already know the domain (e.g. cpython might not be the best place to start if you never implemented an interpreter before, you may spend more time learning about interpreters than the design of this one, still a good thing to learn of course.)

I made a small list long while ago, but it still holds today

https://medium.com/@012parth/what-source-code-is-worth-study...

There's no. Most of production codebase outthere is result of hacks.

study modern code bases of language you want to learn, and look first at their history to see if they are mature, came from a company, academics etc.

you should not only study 'good' code... how will you know what is bad code?

study code that does similar things to what u want (client/server/game/ai/datacrunching etc.) and study lot of it..different qualities, ages, and sources

I've done this for years and swear by it.

Top 5 codebases for changing my mind about things:

Wietse Venema's Postfix mail server. Taught me tons about security posture, the architecture i'd describe as microservices before microservices was a thing, but contrary to the modern take on microservices (it's mostly a tool for decomposing work across large semi-isolated groups) this was primarily about security and simplicity.

Spring framework - this opened my eyes to ways of working that i hadn't really thought enough about before, the developers on that project have a culture of deeply considering the needs of their users (who are java developers often in an enterprise environment).

Git - the thing i like about the git code base is that once you've covered the objects database (e.g. blobs, trees and commits) and the implementation of refs, everything else just feels like additional incremental features. With those core concepts, everything else is kinda harmoniously built on top.

Varnish by Poul Henning-Kamp is another one - feels like he went to great lengths to make that code base a teaching tool despite the fact it's also a top tier reverse proxy.

Last one isn't a code base - but it will help with software design in the large; studying how the lieutenants model works in the linux kernel.

Thinking about my answers, i think i've highlighted something subtly different than "well designed codebases" it's more a list of codebases that left a notable long lasting impression on me because of design decisions they made.

>well designed codebases

One thing to keep in mind is that what was well-designed 30, 20 or 10 years ago may not be considered such now. Hardware changes and so do the design decisions involving performance.

For example, if you are looking at C++ networking libraries, learning from ACE or even Asio may not be the best idea - better look at "thread per core, share nothing" Seastar[0].

Another thing is that it may be better to read design docs, not the code. For example, the rationale for the mold linker design[1].

[0] https://docs.seastar.io/master/tutorial.html#asynchronous-pr...

[1] https://github.com/rui314/mold/blob/main/docs/design.md