Laws of Software Engineering

𝗪𝗵𝘆 𝗖𝗼𝗺𝗽𝗹𝗲𝘅 𝗦𝘆𝘀𝘁𝗲𝗺𝘀 𝗖𝗮𝗻𝗻𝗼𝘁 𝗕𝗲 𝗕𝘂𝗶𝗹𝘁 𝗙𝗿𝗼𝗺 𝗦𝗰𝗿𝗮𝘁𝗰𝗵 Most working complex systems were not designed. They grew. This is Gall's Law, written in 1975 by John Gall, a pediatrician who studied how systems fail: "A complex system that works is invariably found to have evolved from a simple system that worked." The reverse holds too. A complex system designed from scratch does not work, and patching it won't fix that. The only fix is starting over with something simple that works. Let's look at some examples from our industry: 𝗙𝗮𝗰𝗲𝗯𝗼𝗼𝗸 started as a profile site for Harvard students. 𝗜𝗻𝘀𝘁𝗮𝗴𝗿𝗮𝗺 started as Burbn, a failing app with check-ins, games, and photos. The founders decided to throw out everything except photo sharing. That simple core became Instagram. 𝗨𝗻𝗶𝘅 started as a small system for a single purpose. It is still running everywhere. Now the failures. 𝗔𝗽𝗽𝗹𝗲 𝗖𝗼𝗽𝗹𝗮𝗻𝗱, 𝗜𝗕𝗠 𝗢𝗦/𝟮, and 𝗪𝗶𝗻𝗱𝗼𝘄𝘀 𝗠𝗼𝗯𝗶𝗹𝗲 all tried to ship complete operating systems from scratch. All three died. Who remembers 𝗚𝗼𝗼𝗴𝗹𝗲 𝗪𝗮𝘃𝗲? It fused email, chat, forums, and a social network into one product. It launched with no clear user and no traction, and Google killed it in 15 months. Designed-from-scratch systems fail because, upfront, you cannot know all requirements and possible failures. Those things you learn from real life and production. The plan can look good on a whiteboard. Then real users show up, and the abstractions you created don't match the work the system actually has to do. This is why the monolith-first rule exists: build the boring monolith. Then learn where the real seams are, and split services off from working code, not from a diagram. Most distributed monoliths are teams that tried to skip that step. There is even a harder version of this law. When a system already does not work, the instinct is to add more rules, more layers, more services, more config. Gall says the opposite. Strip it back to a working core. The honest move is a rewrite that does less. We don't get to skip the simple working version. Every system that survived went through one. What complex system have you seen fail because it was designed instead of grown?

𝗗𝗼 𝗬𝗼𝘂 𝗞𝗻𝗼𝘄 𝗧𝗵𝗮𝘁 𝗠𝗶𝗰𝗿𝗼𝘀𝗼𝗳𝘁 𝗢𝗻𝗰𝗲 𝗦𝗵𝗶𝗽𝗽𝗲𝗱 𝗮 𝗠𝗲𝗺𝗼𝗿𝘆 𝗟𝗲𝗮𝗸 𝗼𝗻 𝗣𝘂𝗿𝗽𝗼𝘀𝗲? The original 𝗦𝗶𝗺𝗖𝗶𝘁𝘆 had a use-after-free bug. It freed memory, then read it again. On DOS and Windows 3.x, it didn't matter, because freed memory wasn't actually reclaimed right away. The bug existed for years, and nobody noticed. Then Windows 95 entered beta, and SimCity crashed. Microsoft did not ask Maxis to fix the bug. Their engineers reverse-engineered SimCity, found the bug, and patched Windows 95 to detect when the game was running. When it was, Windows switched to a special memory allocator that never returned memory to the OS until the game exited. Microsoft shipped a memory leak to keep a buggy game working. This is Hyrum's Law: "With a sufficient number of users of an API, it does not matter what you promise in the contract. All observable behaviors of your system will end up depending on somebody." Hyrum Wright noticed this at Google around 2011. Changes to internal libraries break some project, somewhere, because that project depended on a behavior nobody had ever written down. The contract is what you wrote, but the actual contract is what the system does. A few ways this shows up: Let's say we have a library function which documenation say it returns an unordered list. But the implementation returns it sorted. Callers start depending on the order. The day you actually make it unordered, their code breaks. Google's older JSON APIs never promised key order. Most libraries are sorted alphabetically anyway. When optimizations started randomizing the order for performance, integrations that relied on positional access broke everywhere. Your API returns a timestamp in a specific format. Someone parses that format. You "clean up" the response. Their integration breaks. The hard part: you cannot prevent this. You can write the cleanest contract in the world. Once enough people use the system, every observable behavior becomes a behavior someone depends on. Performance, error wording, field order, memory layout, timing. All of it. This is why mature platforms move slowly. Why do deprecation cycles last for years? Why Linus Torvalds has spent decades enforcing "we do not break userspace." The everyday version: every internal API in your company has this property. The moment a second team integrates with your service, you have inherited a contract larger than the one you wrote.

More on the Law of Leaky Abstractions, with diagrams and related laws: lawsofsoftwareengineering.com/laws/law-of-le…

George Box: all models are wrong, some are useful. Every schema, every contract, every framework is a model. Yours will leak. The question is whether you know where.

Frameworks promise you don't have to think about the layer below. The Law of Leaky Abstractions says you do. "All non-trivial abstractions, to some degree, are leaky." — Joel Spolsky, 2002 🧵

𝗛𝗼𝘄 𝗜 𝗱𝗲𝗰𝗶𝗱𝗲𝗱 𝘁𝗼 𝘄𝗿𝗶𝘁𝗲 𝗺𝘆 𝗳𝗶𝗿𝘀𝘁 𝗯𝗼𝗼𝗸? The moment I knew I had to write this book was when I realized half the things in my engineering notebook already had names I'd been collecting lessons for years. Patterns from production incidents, team dynamics, and bad architecture decisions. Then I started reading more, and the same patterns kept showing up with names attached. Conway's Law. Hyrum's Law. Brooks. Hofstadter. People had been naming these things for decades. I'd just been rediscovering them. So I wrote them down properly, with the ones I'd found on my own. 2.5 years later, that became Laws of Software Engineering. It's the #𝟭 𝗕𝗲𝘀𝘁 𝗦𝗲𝗹𝗹𝗲𝗿 𝗶𝗻 𝗦𝗼𝗳𝘁𝘄𝗮𝗿𝗲 𝗘𝗻𝗴𝗶𝗻𝗲𝗲𝗿𝗶𝗻𝗴 𝗼𝗻 𝗔𝗺𝗮𝘇𝗼𝗻 right now. One reader bought a second copy for his tech lead. Another read Part II on a flight and restructured his team around Conway's Law before landing. 𝗪𝗵𝗲𝗿𝗲 𝘁𝗼 𝗴𝗲𝘁 𝗶𝘁 📘 eBook (PDF + ePub): techworldwithmilan.gumroad.com/l/lawsofsoftwa… 📔 Paperback, Hardcover, Kindle on Amazon: amazon.com/dp/9699893680/…

More on Tesler's Law, with diagrams and related laws: lawsofsoftwareengineering.com/laws/teslers-l…

When something feels easier, the work doesn't go away. Someone moved it. The only question is whether they moved it well.

Simple software isn't simple. Someone is just doing the hard part for you. Tesler's Law: "Every application has an inherent amount of irreducible complexity. You can't eliminate it, you can only shift who handles it." 🧵

Oh, and check out the terrific accompanying site from @milan_milanovic that lets you browse each law of software engineering ... lawsofsoftwareengineering.com