The Software Developer's Common Sense

Principles, Judgment and the Craft of Building Software That Lasts

Introduction: The Case for Common Sense

1. A Bug That Cost Millions
2. What Common Sense Is (and Is Not)
3. The Five Questions Experienced Developers Ask
4. How to Use This Book

Chapter 1: The Common-Sense Mindset

1. Two Kinds of Complexity
2. Judgments, Not Rules
3. One-Way Doors and Two-Way Doors
4. Cost Over Time
5. Knowing What You Don’t Know

Chapter 2: Problems, Requirements and Change

1. The Real Problem Is Rarely the Stated Problem
2. Eliciting and Expressing Requirements
3. Scope, YAGNI and the Planning Dilemma
4. Estimation and Prioritization as Reasoning

Chapter 3: Simplicity

1. The Compounding Cost of Complexity
2. What Simple Actually Means
3. Techniques for Staying Simple
4. When to Complicate on Purpose

Chapter 4: Code Quality and Readability

1. Code Is Read More Than It Is Written
2. Naming and Local Clarity
3. Small Functions and Flat Control Flow
4. The Same Logic, Three Ways

Chapter 5: Structure, Abstraction, Modularity, Coupling and Cohesion

1. Why We Abstract and What It Costs
2. Modules and Single Responsibility
3. Deep Modules and Information Hiding
4. Coupling, Cohesion and the Direction of Dependence

Chapter 6: Design Patterns, Anti-Patterns and Judgment

1. Patterns as a Shared Language
2. A Practical Tour of Patterns
3. The Anti-Patterns That Do the Most Damage
4. The Meta-Pattern of Restraint

Chapter 7: Testing and Confidence

1. What Testing Is Actually For
2. The Test Pyramid and Its Trade-offs
3. Test-Driven Development, Honestly
4. Flaky Tests and the Cost of Untrustworthy Tests

Chapter 8: APIs, Interfaces and Dependencies

1. Designing Interfaces People Will Depend On
2. Contracts, Versioning and Backward Compatibility
3. Managing the Dependencies You Take In
4. Frameworks, Libraries and the Framework Tax

Chapter 9: Architecture, System Design and Distributed Systems

1. What Architecture Is and Isn’t
2. Monoliths, Services and the Shape of the System
3. Conway’s Law and Organizational Reality
4. The Fallacies of Distributed Computing
5. Designing for Failure and Scale

Chapter 10: Performance and Scalability

1. Measure Before You Optimize
2. Bottlenecks and How They Move
3. Caching, Batching and Layering
4. Throughput, Latency and the Tail
5. When to Scale and When to Stop

Chapter 11: Data and Databases

1. Data Is the Thing You Cannot Get Back
2. Modeling Before You Pick a Database
3. SQL, NoSQL and Consistency, Honestly
4. Migrations, Replication and Sharding

Chapter 12: Reliability, Observability and Debugging

1. Reliability Is Designed In, Not Bolted On
2. The Three Pillars of Observability
3. A Debugging Method That Scales
4. Post-Mortems and the Culture of Failure

Chapter 13: Security

1. Threat Modeling Before You Build
2. The OWASP Map
3. Least Privilege and Defense in Depth
4. The Human and Supply-Chain Layer
5. The Cost Asymmetry

Chapter 14: Technical Debt, Refactoring and Legacy Systems

1. What Technical Debt Really Is (and Isn’t)
2. Refactoring as Risky, Managed Change
3. The Strangler Fig and Living with Legacy
4. Why “Just Rewrite It” Usually Loses

Chapter 15: Building, Shipping and Operating

1. Version Control as a Discipline
2. Continuous Integration and Delivery
3. Deployment Strategies and Reversibility
4. Infrastructure as Code and Environment Parity

Chapter 16: Teams, Review, Communication and the Long-Term Strategy

1. Code Review Done Right
2. Estimation, Planning and Commitments
3. Communication and the Bus Factor
4. What Actually Drives Developer Productivity
5. Long-Term Engineering Strategy

Conclusion: The Common Sense That Compounds

References