CompiledNotes on the software books developers actually reread

All guides

45 original guides across 5 shelves — the full index of everything on Compiled. A complementary collection of engineering lessons is available in Software Engineering at Google.

Code Quality & Craft

Clean Code: What “Clean” Actually Means When You Can't Agree

Robert C. Martin's book gave a generation of developers a shared vocabulary for code quality — and a shared argument about where that vocabulary runs out. The interpersonal side of collaboration is discussed through a different lens in more details here.

7 min read

Refactoring: Changing the Structure Without Changing the Behavior

Martin Fowler's book gave a precise name to something developers already did informally — and the precision turned out to matter.

7 min read

Code Smells: Naming the Problems Before You Can Fix Them

A code smell isn't a bug. It's a pattern that correlates with deeper problems often enough to be worth a second look.

6 min read

Technical Debt: A Metaphor That Explains More Than It Should

Ward Cunningham's financial metaphor for imperfect code became one of software's most-used terms — and one of its most-abused.

6 min read

The Boy Scout Rule: Small, Constant Improvement vs Big Rewrites

“Leave the code better than you found it” sounds simple. The discipline is in how small “better” is allowed to be.

6 min read

Naming Things: Why the Hardest Problem in CS Isn't a Joke

The line about naming being one of the two hard problems in computer science gets repeated as a joke. The underlying difficulty is real and specific.

6 min read

Code Review: What a Good Review Actually Checks For

Most code review advice focuses on tone. The more useful question is what a review is actually supposed to catch that other steps don't.

6 min read

DRY vs WET: When “Don't Repeat Yourself” Repeats Itself Into a Mess

DRY is one of the most quoted principles in software engineering, and one of the most commonly over-applied.

6 min read

Legacy Code: Working With What You Didn't Write

Michael Feathers' definition of legacy code has nothing to do with age — and that reframing is what makes the advice around it useful.

7 min read

Software Design & Architecture

SOLID: Five Letters, Five Habits, One Overused Acronym

The five SOLID principles are widely cited and unevenly understood. Some hold up better under scrutiny than others.

8 min read

Design Patterns: What the Gang of Four Actually Solved

The 1994 book gave recurring design problems shared names. What it didn't do is make every pattern equally worth using today.

7 min read

A Philosophy of Software Design: Complexity as the Real Enemy

John Ousterhout's book names complexity itself, rather than any specific bad practice, as the thing software design is actually fighting.

7 min read

Coupling and Cohesion: The Two Numbers Architecture Is Built On

Most architectural advice is really about optimizing two underlying properties. Naming them directly makes the trade-offs clearer.

6 min read

Monoliths vs Microservices: A Trade-off, Not a Verdict

The industry conversation often treats this as a question with a right answer. It's really a question with a right answer for a specific system, at a specific size, at a specific time.

7 min read

The Mythical Man-Month: Why Adding People Slows a Late Project Down

Fred Brooks' 1975 book made an observation about software project management that's still cited, and still routinely ignored.

6 min read

Conway's Law: Why Your Architecture Looks Like Your Org Chart

A 1967 observation about organizations designing systems that mirror their own communication structure still predicts a lot about modern software.

6 min read

Domain-Driven Design: Modeling the Problem Before the Code

Eric Evans' central argument is that most software problems are modeling problems in disguise — and the model deserves as much design attention as the code.

7 min read

YAGNI: The Discipline of Not Building It Yet

“You aren't gonna need it” sounds like an argument against planning ahead. It's actually an argument about where the cost of guessing wrong lands.

6 min read

Process, Testing & Delivery

Continuous Delivery: Shipping Small Changes, Safely, Often

Jez Humble and David Farley's book argued that the safest way to ship software is to ship it constantly, in small pieces — the opposite of the intuition behind big, careful releases.

7 min read

Test-Driven Development: Writing the Test Before the Code

TDD's red-green-refactor cycle sounds like a small procedural detail. The order turns out to change what the resulting code looks like.

7 min read

The Testing Pyramid: Why Most Tests Should Be the Boring Kind

A simple shape — more unit tests than integration tests, more integration tests than end-to-end tests — explains a lot about why some test suites are fast and reliable and others aren't.

6 min read

Code Freezes and Release Trains: Two Ways to Manage Risk

Two very different scheduling philosophies for the same underlying problem: deciding when a change is allowed to ship.

6 min read

Postmortems: Writing Up a Failure Without Assigning Blame

A good incident postmortem is a specific writing discipline, and the discipline matters more than most teams expect.

6 min read

Feature Flags: Decoupling Deployment from Release

A feature flag looks like a simple if-statement. The idea underneath it separates two decisions that most software conflates by default.

6 min read

Pair Programming: What Two People Actually Buy You

Two developers working on one problem at one machine sounds like it should cost twice as much output. The real accounting is more complicated.

6 min read

The Cost of a Bug: Why It Gets More Expensive the Later You Find It

A widely cited claim in software engineering holds that a bug found in production costs far more to fix than the same bug found earlier. The reasons why are more specific than “it's just true.”

6 min read

Definition of Done: Making “Finished” Mean Something Specific

Two developers can honestly disagree about whether a task is done. A written definition exists to remove that disagreement before it causes a problem.

6 min read

Developer Careers & Communication

The Pragmatic Programmer: Craft Advice That Outlasted Its Examples

Andy Hunt and Dave Thomas's book is full of dated technical examples and a set of underlying habits that haven't dated at all.

7 min read

The Clean Coder: Professionalism as a Practiced Skill

Robert C. Martin's follow-up to Clean Code argues that professionalism in software isn't a personality trait — it's a specific, learnable set of practices.

6 min read

Impostor Syndrome in Engineering: A Common Feeling, Poorly Named

The term gets used constantly in software culture. What it actually describes, and doesn't, is worth being precise about.

6 min read

Writing an RFC: Making a Technical Decision Legible to Others

An RFC document is a specific writing discipline for a specific problem — getting a decision reviewed before it's expensive to change.

6 min read

Giving Feedback on Someone Else's Code Without Being a Jerk

The tone advice around code review is well-worn territory. A few specific, concrete techniques do more than general kindness reminders.

6 min read

The Senior Engineer Question: What Changes Besides the Title

Seniority in software is often described vaguely as “more experience.” What actually changes is more specific than that.

6 min read

Saying No to a Deadline: Estimation as a Negotiation Skill

An estimate isn't just a number — it's the opening move in a negotiation most developers don't realize they're having.

6 min read

Mentoring Junior Developers: What Actually Transfers

Good mentoring isn't just answering questions faster than a search engine would. What actually transfers is harder to see and easier to skip.

6 min read

Burnout in Software Teams: Recognizing It Before the Sprint Does

Burnout in engineering culture gets discussed as an individual failure to manage stress. The research points more toward systemic causes.

7 min read

Documentation & Developer Experience

READMEs: The Most-Read File Nobody Budgets Time For

A README is very likely the single most-read file in most repositories, and very likely the least deliberately written.

6 min read

API Design: Naming, Consistency, and the Cost of a Breaking Change

A well-designed API is mostly a set of small, consistent decisions. A poorly designed one is usually the sum of many individually reasonable exceptions.

7 min read

Versioning: What Semantic Versioning Actually Promises

A version number formatted as X.Y.Z looks simple. What each part is supposed to communicate is more specific, and more often violated, than most users realize.

6 min read

Writing Docs Developers Actually Read

Most technical documentation is written to be comprehensive. Most of it is read to answer one specific question, fast.

6 min read

Error Messages as a Design Surface, Not an Afterthought

An error message is one of the few pieces of documentation a user reads exactly when they need it most — and most of them are written with almost no care.

6 min read

Changelogs: A Small Habit With an Outsized Payoff

A changelog is one of the cheapest documentation habits available, and one of the most commonly skipped.

5 min read

Onboarding a New Developer: What the First Week Should Teach

A new developer's first week is often measured by how fast they ship something. What it actually should teach is broader than that.

6 min read

Deprecation: Removing Something Without Breaking Everyone

Removing a feature safely takes more deliberate process than adding one — and most of that process is communication, not code.

6 min read

Developer Experience (DX): Treating Internal Tools Like a Product

The tools a team builds for itself rarely get the same design attention as the product it ships to customers. DX is the argument that they should.

6 min read