33. Responsibility Driven Design 101
33. Responsibility Driven Design 101 -Driven Design is the influential object-oriented design method with which we can use to intentionally drive the design of object-oriented software. What follows is the essential philosophy of RDD, from responsibilities to stereotypes, components, object neighbourhoods and beyond. Use the RDD methodology to convert requirements into neighbourhoods of collaborating objects. Introduction In psychology, the concept of frames describes the way you see the world. Take being stuck on a train. Where one person may resist the situation, grow frustrated and treat it as a net negative occurrence, another may see it as an opportunity! Ah, wonderful — a chance to meditate, catch up on some reading, or start a conversation with a stranger. How lovely. Essentially, your frames are your bearings on the world, your interpretation of reality, your cognitive biases. In this book, I've asked you to adopt a number of phronimos frames on software development. These frames probably challenged the way you normally did things. So commonly, when I sit down and craft designs with developers, I find that there’s a tendency to see software as a Rube Goldberg machine of library concepts, frameworks, and platform features. I also note a tendency to jump straight to thinking about things like API endpoint names, databases, and which state management library we’re going to use on the front-end. This conditioning to focus on the imperative is one of the first things I want to decompose. We’ve done some work here already. With the notion that 13. Features (use-cases) are the key, we shift to a focus on the behaviour instead of database-first, API-first, or tooling-first ways. This drives us to increase the importance of learning things like BDD, DDD, acceptance testing, identifying the use cases, and now, to develop object-oriented software, object-oriented design. If we’re already thinking in terms of behaviour, then the next shift we need to make is easy. It’s a shift to see behaviour as responsibilities. Personally, this frame shift came from reading the legendary Object Design book, particularly the following quote: “Object-oriented applications are composed of objects that come and go, assuming their roles and fulfilling their responsibilities.” — Rebecca Wirfs-Brock Meditating on this statement, seeing behaviour as responsibilities, we illuminate the path to mastery for many topics including testing, when to mock, stub, how to implement non-functional requirements, deal with architecture on both sides of the stack, and use frameworks, libraries, and many other tools effectively. Responsibilities are the next step. I’d like you to have a similar revelation. So in this chapter, we’re going to learn the philosophy of Responsibility-Driven Design. I hope you never see code the same way again. Chapter goals In this chapter, we: Learn the philosophy of Responsibility-Driven Design. Learn how to think about objects from an RDD point of view. Learn about the six object stereo object stereotypes and how they can help you more invent and understand how objects should collaborate. Object basics Let’s break down this new frame of object-oriented software development by revisiting a concept that might seem silly to talk about at this point, but we’re doing it anyway: objects. Object capabilities Hopefully this doesn’t come as a surprise to you, but in the world of object software, the object is the fundamental tool. Objects have four main purposes. To know information: We know this. Information objects hold is called state. For example, a object holds personal data such as name, email, or preferences. To make decisions: They use methods (often reliant on state) to define meaningful business rules, algorithms, and scripts that help decide on the right thing to do. For instance, an object may calculate a total price or apply discounts based on criteria. To advertise their services: Objects are only useful when they’re used by other objects. To do this, we introduce public methods and make interactions predictable. To maintain connections to other objects: Objects collaborate by delegating work to others. They use composition or delegation (and sometimes subclassing) to share responsibilities. This is how you break down complex problems into manageable, interacting parts. /book-assets/Software Design and Architecture Wiki 16ec9c6a09b3410ca7be7920be75e128/Part V Object-Oriented Design With Tests 7c9c10572cc54aa195e8ec661cf88312/33%20Responsibility%20Driven%20Design%20101%20f9e50d384f7e4fe393c70cda53c134ff/Untitled.svg 💡 Note on Relationships: Think of the relationship as “played by”—an object “plays” a particular role rather than simply “is a” type of another object. This idea, borrowed from role-oriented programming, emphasizes that objects fulfill responsibilities, and different objects can step in to perform the same role when needed. Why is this significant? Well, with these four capabilities, we make the…
Introduction
Introduction My story It all started when my interviewer asked me, "How would you design your business-logic layer?" I'm sitting there in the middle of a dimly lit room, in front of three senior software developers, (none of them looking very pleasant I might add), hoping that not a single one of them catches a glimpse of the bead of sweat I just felt roll down the side of my head. Business-logic layer... That's practically another language to me. I hadn't the slightest idea of how to answer it. After a few seconds of deliberation, I started to say words. I probably said something about MVC (model-view-controller), how I organize my folders, and maybe something about how I structure my controllers in a Node.js & Express.js project. Every word leaving my mouth was an extra bit of dirt flung into the hole I was digging for myself. As I was speaking, I was realizing more and more that nothing I said had anything to do with "business-logic". Eventually, the sense came over me to stop speaking. I was then met with a very uncomfortable couple of seconds of silence. After a head nod from one of the fellows and some glances at each other, one interviewer said "OK, I think that'll be about it. Thank you, do you have any questions for us?" Aaaaaaab-solutely not, I'll see myself out — said my brain. Trying to erase that moment from my memory as soon as possible, I probably asked "So, what's the culture like here?" Safe to say, I didn’t get the job. My recruiter even dropped me. Thinking back to what I did to prepare myself for the interview, I remember studying: Whatever I found off of the "how to prepare for a full-stack web developer interview" Google search The algorithms in Cracking the Coding Interview Javascript and all its silly language quirks like closures, IIFEs, and passing by reference vs. value. Not only that, but I had been working on building my own startup company during the time I was in school, and I thought that all that code I wrote would have translated into some serious experience. I may have completely bombed that interview, but looking back today — that was one of the best things that could have happened to me. It was that moment that I realized there was an entire world of software design and architecture that I needed to teach myself. I became incredibly interested in this topic. I was going to learn. And I wasn't going to fail the next interview. My early research Mid-2018, in the middle of my research, I really needed to pay the bills, so I ended up landing a job as a Frontend Consultant. I was mostly looking for a low-stress job I could perform to hack my career by purchasing and studying as many books on software design, patterns, and architecture as possible and applying everything I learned from those books to improve my cumbersome ~300k-line Node.js startup code. Every evening after work for 8 months, I read books and wrote code. I reviewed everything they taught me in school, but this time, learning from the experts' books. I started with Object-Oriented Programming. What were the 4 principles of OOP again? What does an abstract class do anyway? Why would you ever want to use a static method? I heard that inheritance was a bad thing, right? Why should I avoid that? As I was learning, I wrote down all of the concepts that I’ve heard of but never really cared to try to understand like POJOs, dependency injection, dependency inversion, inversion of control, concrete classes, design patterns, and principles, etc. I revisited ideas that I knew about but never fully understood in depth like coupling, cohesion, managing dependencies, and separation of concerns. Soon, I was learning a lot of new things like the hexagonal architecture, Conway’s law, Use-case driven development, TDD, and the SOLID principles. The point where it all really felt like it paid off was when I discovered Domain-Driven Design. My learning approach was to learn by doing in addition to teaching others. I quit my job, refactored Univjobs' codebase using Domain-Driven Design practices, and began to regularly share what I was learning about software design and architecture with my peers online on my personal blog. Today, thousands of readers every month are learning how to write testable, flexible, and maintainable code @ khalilstemmler.com. Why I wrote this Two years later, after about seventy-or-so blog posts, ten thousand newsletter subscribers, and the dissolution of Univjobs, I wanted to work on building a Domain-Driven Design course. It was the most useful topic I discovered on the blog, and it also seemed to be pretty popular. As I started to learn more about who was interested in this course, I realized that the skills gap in software design skills was deep. Maybe there were bigger fish to fry. Practical design skills aren't being taught The truth is, not a lot has changed about the fundamentals of software design over the past 60 years, but there's a huge lack of training on it. By and large — junior and…
40. Behavioural Patterns
40. Behavioural Patterns 💡 Behavioural patterns manage object interactions and responsibility distribution. They can standardize algorithm structures (Template Method), encapsulate complex communication (Mediator), enable event-driven updates (Observer), swap algorithms (Strategy), or handle collection traversal (Iterator). Chapter Goals Explore five common behavioral patterns. Understand frontend vs. backend/DDD use cases for each. 1. Template Method First up is the Template method. This pattern defines the skeleton of an algorithm in a base class, deferring some steps to subclasses. The beauty is that it allows a shared algorithmic structure while different subclasses can override or implement the details. Real-life scenarios Backend/DDD: Different domain services share a similar workflow (e.g., handling a “process order” flow), but certain steps vary (e.g., shipping rules differ per country). Frontend: Different UI flows share a common sequence (e.g., load data, transform data, render UI) but differ in the transformation step. Code Example Frontend Use Case A base React/Vue component that has a standard lifecycle (e.g., ), but a subclass can implement custom logic. Backend/DDD Use Case A domain “OrderProcessingTemplate” might define steps like , , . Subclasses handle specific variations (e.g., digital goods vs. physical goods). My thoughts on this pattern? This is such a cool pattern. To really appreciate it, think about every single React Component you’ve ever written when we the class-based version of React was popular. Back then, we had , , etc. Even the method! These are all template methods that had to get called by React’s view layer engine behind the scenes. The thing is, the actual code in them (which you write) can be different. It’s like a rough recipe. Or, like a consistent skeleton that allows override for crucial steps. 2. Mediator The next is the Mediator. This pattern encapsulates how a set of objects interact, so that they don’t refer to each other explicitly, leading to loose coupling. Loose coupling is good, my friend. What’s the problem it solves? Tight coupling, my friend. Basically, it prevents a web of direct communications—many objects calling each other—by centralizing communication in a mediator. Let’s take a look at an example. An orders example Backend/DDD Use Case Supposedly, we can use them as a “Service” orchestrating domain entity interactions: e.g., an that sends notifications, updates inventory, etc., so entities don’t call each other directly. But… My thoughts on this pattern? Honestly, I don’t really like this pattern very much. To me, I think we could just decouple using Infra → Application Layer → and then call domain objects. In my opinion, domain objects shouldn’t know about “mediators” because that means nothing within the context of an “Order” entity/aggregate. Alas, maybe there’s something I’m not seeing, but I haven’t had a good reason to use this pattern ever yet. When you see how we handle this in Part IX: Building Web Applications with Domain-Driven Design, Hexagonal Architecture and CQRS, I think you’ll agree that we don’t need this. 3. Observer The Observer pattern, however — is one I’m constantly using. It defines a one-to-many relationship. When the subject changes, all of its observers are notified and updated automatically. What’s the problem it solves? It enables event-driven or reactive updates among objects without tight coupling. Real-world scenarios Frontend: A reactive state system (e.g., Vue/React) where components observe store changes. Backend/DDD: A domain event system where multiple event handlers (observers) respond to one domain event (subject). Code Example Frontend Use Case A Redux/Vuex store that notifies subscribed components whenever data changes. Backend/DDD Use Case A domain event mechanism: e.g., an event notifies multiple interested “observers” (send email, update CRM, record analytics). My thoughts on this pattern? You’re always using this one. It’s deep in your frontend view layer libraries and your state management code. The cool thing about this, is that when you learn how to use mobx, you can actually set up an entire frontend architecture without needing stuff like Redux or whatnot. You just need an observable object. You may end up saying: “The observer pattern made it easy to add new reactive features without altering existing code.” 4. Strategy This pattern defines a family of algorithms, encapsulates each, and makes them interchangeable at runtime. The benefit is that it eliminates large or blocks for choosing an algorithm, making it easy to swap or add new strategies. Real-world scenarios Backend/DDD: Payment strategy (CreditCard, PayPal, etc.), or shipping calculation (by weight, by distance). Frontend: Sorting different columns with different sorting algorithms, each as a strategy. Code Example Frontend Use Case A UI that changes how it filters or sorts data based on user selection (e.g., “Sort by Name,” “Sort…
Sept 8th, 2023 update
Sept 8th, 2023 update Hello readers What’s going on, Crafters? It has certainly been a while since our last update here, primarily because I’ve been deeply engaged with the course students. Let’s take a moment to recap what’s happened and where the dust has settled. Let’s recap Why did I start writing this book again? The entire reason I started writing solidbook was because it was quite distressing to me, this experience of graduating from 5 years of school only to find I was still unable to do much of what actually mattered. As you may know, I’ve poured over countless books, applied as much as I could, and started assembling it into this book here! How did it go? What began as a book idea evolved into a wiki. I eventually reached a point where I stopped finding new foundational topics to explore, and shifted over to recognizing recurring patterns. This knowledge was then passed on to my mentorship students. I introduced 'The Software Essentialist' course to continue refining these concepts with real-world developers. Now, with over 500 developers in our course community and several content iterations later, I'm excited to present the finalized outline for the course and the book. But first, I want to share some pivotal lessons from this transformative journey. I’ll share the outline with you shortly, but first I want to tell you some of the main things I’ve learned throughout this crazy endeavour to piece together and distill the wisdom of the experts from the last 40+ years and create a path for junior developers to master what actually matters. 9 Lessons I’ve Learned Realized the following things The ultimate aim here is design confidence. But if you’re don’t know what matters, you’ll always be second guessing yourself The foundation lies in understanding the first principles and mental models rooted in reality. A developer's primary mission is to benefit 3 roles: Users, Customers, & Fellow Developers. To elaborate: Users seek time saved or enriched. Customers pursue revenue growth or protected revenue. And Developers crave a versatile codebase that doesn't compromise the goals of the former two. Achieving this balance? Quite a challenge, but that's the essence of scalability. Scalability hinges on mastering the 4 Pillars: Design, Testing, Architecture & Strategy. Acquiring proficiency in the 4 Pillars can span years without the right mental models. Abstraction & The Feedback Loop (Systems Thinking) are paramount mental models for every single software developer. Gain a deep understanding of these and how they apply to code, and many of your problems go away with practice. To attain Design Confidence means you need to master Problem Decomposition, and those two mental models are the keys. This attain Mastery of this skill involves ascending through distinct 5 Phases of Craftship. And, this forms the backbone of the book's final structure. The final course & book outline Intro Why I Wrote This Book & How It Came To Be — A Quick Recap of the History Of solidbook & The Software Essentialist The Roadmap — How to Skip the Status Quo & Master Problem Decomposition & Confidently Write Scalable Code On Any Side of the Stack The Software Essentialist Mindset — The Core Mindsets You Need For Success Along The Path The Metaphysics: Developing a solid understanding of the first principles and how to think about code. The Mental Models: The 80-20 of Software Design, Testing, Architecture & Strategy — Understand Software Software Design, Testing, Architecture & Strategy from First Principles in 12 Essentials The Skills — An Introduction to the Systems Thinking Techniques (FA²STR, The Guess Points, The Stereotypical Architecture) Which Help You Systematically Decompose Design Problems & Approach Your Work in a Consistent Way The Phases of Craftship: A gradual, step-by-step approach to learn how to implement techniques from the 12 essentials of design, testing, architecture & strategy. Code-First — Basic practice building an information system from End to End using MVC Best Practice-First — Learn build, test & deploy a Walking Skeleton to a Minimal Deployment Pipeline Pattern-First — Learn how to use DDD, Hexagonal Architecture & decouple from infrastructure, refactor to patterns to encapsulate complexity & introduce powerful testing strategies on both the frontend and backend Responsibility-First — Learn how to balance coupling & cohesion and design anything using the timeless 3-Step Responsibility-Driven Design process Value-First — Learn how to use the Systems Thinking-based FA²STR Design Method to Decompose Any Design Problem & Continually Improve Your Skills As a Value-First Developer (5 Feature Demonstrations) The Guess Points: A catalog of Systems to aide in your continued Problem Decomposition Understanding the Guess Points: Theoretical & Physical The Problem Guess Point — Learn how to ensure you’re building the right thing The Solution Guess Point — Learn how to come up with a solution and identify the…
The Structural Style
The Structural Style We’ve encountered many potential structural architectures—Monolithic, Layered, Component-based (Hexagonal), Microservices, Client-Server, Peer-to-Peer, Broker, Service-Oriented… etc. Yet in practice, most beginners (and many established teams) commonly focus on these three: Monolithic — one deployable unit, can be well-structured internally. Layered (n-tier) — a classic approach dividing domain, application, and infrastructure. Hexagonal (Component-based / Ports & Adapters) — domain in the center, adapters around. Often, you combine them: e.g., you have a monolith that internally is layered or hexagonal to keep domain logic clean. In this section, we’ll review a number of them. Continue reading Model-View Controller Architectural Pattern
Pick your object-modeling poison
Pick your object-modeling poison In my experience, this mismatch between the responsibility of the model in MVC and beginner-level tutorial code that promotes slim ORM models makes it hard to interpret where business logic should go. This confusion manifests as one of three (poisonous) options: A: Controller holds business logic - Put business logic in the controller (which isn’t correct) and is only an option because putting it in the Sequelize ORM model is going to feel dirty. B: Start creating “services” to hold business logic - It’s a common (dangerous) thought pattern that anything that doesn’t naturally fit within the confines of three constructs of MVC (model, view, controller), is a service. You might find that this approach is a quick train ride to writing code that has no Single Responsibility and contributes towards a turning a codebase into an Anemic Domain Model, which is as bad as it sounds. C: Do the dirty thing and put the business logic inside the Sequelize ORM model as an instance method. I don't recommend this. Sequelize is an infrastructure-layer concern and needs an active database connection to use. Putting the domain logic here means that any unit tests relying on Sequelize will be slow since we have to account for the additional overhead of setting up and tearing down tables and connections. This is not clean at all. Sequelize (and any other infrastructure-layer technology) should be far from the domain logic. Choosing one of these options is problematic, indeed. None of them are great, yet the poison most developers pick is A: controllers hold the logic. Let's entertain that: What I just presented is how I wrote code for a long time. Unfortunately, there are several drawbacks: I have to repeatedly write this permission logic in every single controller to see if I have access to a resource. We're returning the entire object raw. If we were to add or change a column on the model, we've potentially broken someone's code that relied on this from the API response. Nowhere in the code do we represent the concept of in this supposedly role-based access management. The concept of a is not explicitly expressed; it's expressed inadvertently through the absence or presence of a database row. That kind of beating-around-the-bush makes it pretty challenging to follow along understand the domain logic quickly. It actually forces readers to read between the lines. The code should read like a book, and it doesn't. Although I named variables expressively, low-level details (Sequelize - data-access logic) are mixed in with high-level rules (role-based access control). This is a bad separation of concerns. These are legitimate problems that need to be solved. And we’ll solve ‘em. That's why "how would you design your business-logic layer" is such an excellent question. "How would you design your business-logic layer" is a good litmus test for the scope of projects a developer has previously worked on. When asked that question, most of the time, developers who have a) never had the chance to work on complex full-stack applications, or b) didn't know how to address a growing application's complex needs, tend to describe MVC. Continue reading Concerns of the unspecified layer in MVC
Summary on use case diagrams
Summary on use case diagrams Use case diagrams and reports are pretty useful tools that you can use to document project requirements and business rules with test cases. I would advocate for using use case diagrams when we understand the domain, and we're ok with doing the majority of the use case modeling work in isolation, away from domain experts who might not understand even the slightest semantics of use case diagrams. However, it can be risky for developers to spend design time alone since we know that it's the initial design of a project that has the potential to have the most profound impact on the overall quality of the system. There must be a design tool that involves both the developers and the domain experts in this process. There is, and it's called Event Storming. Continue reading Event Storming
6. Organizing things
6. Organizing things 💡 By structuring your application's folders and architecture around the use cases, you end up with an expressive and discoverable project structure that makes it easy for you and future maintainers to quickly understand what the system does. Packaging use cases into cohesive folders promotes feature decoupling and improves your ability to find, add, change, and remove features. This is an approach that can be applied to both back-end and front-end projects. Chapter goals Learn the symptoms of poor project structure Discuss the shortcomings of common approaches to project structure Learn the benefits to structuring your project around the use cases of the system Learn how to structure front and back-end projects for discoverability, cohesion, and expressive Symptoms of poor project structure Forgetting what the system does How many times have you worked on a side-project, left it for a few months, and then came back and tried to remember what the heck it does? Some project structures force you to expend extra energy to remember what the system can do. Hard to locate features "Ah, after you login, I want you to be redirected to the dashboard page instead of going to the latest posts". How long does it take you to find the login feature and all the code associated with it? Energy spent flipping back and forth between files Let's say you've found the component that renders the login form. You need to change a couple of different things related to this feature like the React hook, the styling on the page, the popup text that comes down after, etc. You want a dedicated workspace to work on one particular feature at a time, and you don't want it to be overwhelming. This distance of these files in your project influence the amount of cognitive load required to make all the necessary changes. Common project structure approaches Here are some of the most common approaches to project structure that I've seen in the wild. Let's assume we're working on a React project for these examples. Just evolve it over time Assuming we're starting from nothing, we're not using TDD, and that we're just building up the application, we start with the following files. Now, over time, we start to craft out new folders and technically separate things. Eventually, we notice that we need some place to store logic that doesn't really belong in components. So we create a folder and start putting functions in there. We also realize that we need some statefulness, so we start to create React hooks too. We watch our folders start to take shape. And it might look something to the form of this: With this approach, we don't start with any particular structure in mind — we just let it evolve naturally. While there's a time and place for this, the major disadvantage of this approach is that it doesn't work very well when there's more than one developer on a project. We may take on a couple of features and the other developer(s) may take on some of their own — how do we decide how we're going to split up the work and how the project should be organized to allow that? This is a recipe for conflicts. It also means we're constantly using brain-power to ask ourselves, "does this belong here?". Will it help us remember what the system does? — No. Will it help us locate features? — No. Will it reduce the distance of flipping between files when working on features? — No. Package by infrastructure/technology/type As excellent pattern matchers, the next logical approach is to organize files into top-level folder categories based on the type of technical infrastructure they belong to. While this may seem like a reasonable design idea, it too comes with its own set of disadvantages as well. The first disadvantage is the amount of cognitive load requires. Features are split across several files and folders and separate from each other. This means that if we've been given the task to change or remove a feature, we're going to have to have an intimate understanding of how that feature is realized across several files and folders — none of which are logically grouped together. The second disadvantage is that if we were to come back to our project after a year with it no longer fresh in our minds, we'd have no idea what it does until we start to peek through the codebase and refresh our memory. The discoverability of the features are remarkably low. That might not be so bad if you were the original author, but consider the case of a new developer trying to learn the codebase for the first time. That would certainly be a much more challenging endeavour. Will it help us remember what the system does? — No. Will it help us locate features? — No. Will it reduce the distance of flipping between files when working on features? — No. Package by domain The last of the three approaches I've most frequently seen is to organize files and folders by the domain that they belong to. In the file structure above, the folder contains a list of generic…
24. An Object-Oriented Architecture
24. An Object-Oriented Architecture 💡 Architecture is meant to support the functional and non-functional requirements. A good architecture is one that does this but also adheres to the most well-known design and architectural principles. In object-oriented business applications, the most important non-functional requirement is the ability to test business logic complexity effectively. I argue that a layered architecture is the superior technique to accomplish this. It lets us write code in a test-first and domain-driven way. Let's keep our eyes on the prize here. We're going to use OO the right way to build out features. How do we get started? We're supposed to TDD our way through them, right? How do we kick-start that process? In XP, our goal is to TDD our way through a story. Using Acceptance Tests, we use a technique called Double Loop TDD. It starts by first writing a failing acceptance test from the outer boundary of the application (now — what outer boundary means to you and which form of tests you use for your outer boundary Acceptance Tests could differ depending on our 25. Testing Strategies). Regardless, after the automated acceptance test fails, we move in a layer, and continuously write inner loop red-green-refactor Unit Tests until the outer loop passes. Once both loops are green, we're done with the feature. Best part? We have tests to prove it too. Now it's time to deploy it. We push it into a CI server, that builds the code, runs the tests, and deploys it if everything passes. That's where we're trying to end up. /book-assets/Software Design and Architecture Wiki 16ec9c6a09b3410ca7be7920be75e128/Part III Phronesis 60b174f15da34fdcb5bc8a099436a9bb/13%20Features%20(use-cases)%20are%20the%20key%20193ca4bbb8604c0eada33d1ac86ed517/Untitled%202.png But we have to back up a little bit. How can we even write the first test if we don't have the infrastructure to support it? Yes, we're going to want to install our testing tools, like Jest and Cypress, of course, but what about the structure of the code itself? What about the architecture? TDD is "doing the simplest possible thing that could work", but we still need to think about design. In fact, when I do TDD, I'm constantly designing. On the whiteboard, on paper, in discussion, and in the patterns I use in my solutions. Here's what we need to do before we can write the first test: Understand the problem Design a rough sketch of our initial architecture Build, deploy, and test a walking skeleton (and use that as our test architecture) /book-assets/Software Design and Architecture Wiki 16ec9c6a09b3410ca7be7920be75e128/Part III Phronesis 60b174f15da34fdcb5bc8a099436a9bb/24%20An%20Object-Oriented%20Architecture%20fc5ef2681c054be2ae628318de0c4cfa/Untitled.svg The context of the first test (from "Growing Object-Oriented Software Guided by Tests — Steve Freeman") With respect to 1. Understanding the problem, we've already done a lot of work on that in 16. Learning the Domain, and 21. Understanding a Story . We understand the problem in the sense of data, behaviour, and namespaces (or domain events/aggregates, use cases, and subdomains in a Domain-Driven Design sense) and we've uncovered a lot of the non-functional requirements too. Skipping the second step for a moment, the third is to Build, deploy, and test a walking skeleton. The walking skeleton is essentially the test infrastructure in which we perform our acceptance-test-driven development loop within. In the next chapter, 26. The Walking Skeleton , we discuss getting this up and running. Now, the second step — creating a broad-stroke design of the architecture. At this point, we have to ask ourselves: how do we determine the shape of the skeleton overall? What does the initial architecture look like? The focus of this chapter is to discuss the design of an initial object-oriented architecture that we'll use ****to inform how we build the platform upon which we'll kick off the TDD loop with. Chapter goals Specifically, we will: Learn how to choose an architecture based on the functional and non-functional requirements Understand why we prefer a layered architecture instead of merely using MVC for business applications Discuss how and why to decouple core code from infrastructure code Understand how we handle requests in a layered architecture Deciding on an architecture How do we decide on an architecture, overall? What are the principles at play that influence how to make this decision? This is an excellent question. If you'll remember, this question is one of the main reasons why I started writing this book. I was personally struggling with MVC while building an application that had a very complex domain. It would have benefited from a different architectural style. Architecture is about the stuff that's hard to change if we get it wrong early on. That said, if I had to make a recommendation on how to make a decision overall, here's what I would do. 1. Use the requirements I know I've said…
50. Arch Principles: The Common Principles
50. Arch Principles: The Common Principles 💡 We’re exploring the fundamental ideas that shape software architecture. We’ll see how each principle addresses a real-life development problem, and how these principles unify to keep our system robust, testable, and aligned with actual features. 1. Vertical Boundaries Real-Life Problem Your team needs to implement a “MakeOffer” feature in an application. You start coding domain logic in a shared “utils” folder, a controller in a separate “controllers” folder, database access in a random “db” folder. Soon, nobody knows where all the “MakeOffer” code is. People keep missing pieces or duplicating logic in weird places. The system becomes spaghetti—it’s impossible to see an end-to-end feature in one coherent flow. Why It’s a Problem Mental overhead: New devs can’t figure out how “MakeOffer” truly works. They have to jump across multiple files, hoping they piece together the entire workflow. Integration pain: Because the code is scattered, finishing the feature requires merging changes from random corners of the codebase. Principle & Definition: “Vertical Boundaries” Vertical boundaries mean building a vertical slice for each feature—an end-to-end path from UI or entrypoint, through domain logic, down to infrastructure. In The Software Essentialist, we call it Vertical Slicing. Each user story forms one slice. Why & How It Solves the Problem Focus: Each slice belongs to a single feature (e.g., “MakeOffer”). If you need to update or debug it, you track it along that vertical path. Completeness: You ship working features end-to-end, not random “utils” or “db classes.” Example Now the devs see a single route: from the UI to domain to DB. The code for “MakeOffer” is discoverable (maybe in a folder dedicated to Offer features — see what we did in 6. Organizing things). No more spaghetti scattered in separate “utils” or “db” modules that aren’t clearly connected. 2. Horizontal Boundaries Real-Life Problem Your big eCommerce system lumps everything in a single folder—controllers and SQL queries living side by side, domain logic mixed with UI utilities. It’s unclear which code belongs to presentation, which code is domain rules, which code deals with data access. Devs often break domain logic by “fixing” the UI layer or vice versa. Why It’s a Problem Separation of concerns is violated: multiple unrelated tasks happen in one place. Difficult to test: UI changes might break domain code. Unit tests become complicated, as there’s no clear layering to mock or isolate. Principle & Definition: “Horizontal Boundaries” We define horizontal layers or boundaries—like UI/Presentation, Application/Domain, Infrastructure—to separate concerns. Think of them as “levels” or “tiers.” Combined with vertical slicing, we get a grid: each feature (vertical) spans each layer (horizontal). Why & How It Solves the Problem Clear responsibility: UI code handles display only. Domain code handles rules only. Infra code handles DB or external services. Easier changes: When domain logic changes, we don’t rewire the entire UI. When we swap a DB, domain code remains intact. Example Now each layer is dedicated to a single type of job. The system reads left-to-right for a feature (vertical), but the horizontal layering ensures domain logic never bleeds into UI code, etc. 3. Contracts Real-Life Problem You’re building a domain service that must talk to a payment system. Initially, you code directly: Later, you want to switch from Stripe to PayPal, or add a test double for local dev. Now you must rewrite code referencing the actual Stripe implementation. That’s messy and can break domain tests. Why It’s a Problem Tightly coupled to Stripe details. Hard to test offline or to replace with PayPal. Changing the payment method requires touching domain code, risking breakage. Principle & Definition: “Contracts” A contract is an interface or API describing “what” a module does. We rely on the contract instead of a specific implementation. This fosters Dependency Inversion: The domain depends on an interface, not a concrete class. Why & How It Solves the Problem Flexibility: Swap out the PaymentProcessor for PayPal or a test double without editing domain logic. Better tests: Domain code references the contract only, so mocking is easy. Example Now the domain (OrderService) is free from details. If we want PayPal, we implement that contract. This solves the earlier problem of rewriting domain code each time we change the payment system. 4. Cross-Cutting Concerns Real-Life Problem Your feature logic is done, but every route or domain method duplicates the same code for authentication or logging: You see the same auth check or logging repeated in many controllers and domain methods. This is tedious to maintain and easy to forget. Why It’s a Problem Redundant code: Dozens of places re-implement the same checks, logging, or transaction management. Bug risk: Missing one method or forgetting to update a log statement can…
Persisting the upvote post operation
Persisting the upvote post operation When implementing DDD without using Event Sourcing, in a transaction, the Aggregate gets mutated, and it needs to know how it was mutated so that we can issue the correct persistence commands to reflect the way it has changed. This is one of the disadvantages of not using Event Sourcing. In Event Sourcing, we persist the state changes themselves, whereas with how we're doing it, we update and overwrite the existing state with the new state. At some point, we must answer the hard questions about persisting Aggregates this way. Continue reading Signaling relationship changes Persisting complex aggregates using database transactions
28. Test-Driven Development Workflow
28. Test-Driven Development Workflow 💡 The best way to write testable code is to write the test first. In a real-world project, we maintain two TDD loops: an outer and inner loop. One for the outer Acceptance Test, and one for the inner Unit Test loops. Once all the tests pass on both loops, we're done implementing the application core. This technique is called Double Loop TDD. Following that, we improve the code by filling confidence gaps with Integration and E2E tests. TDD gives us the opportunity to safely exercise the entirety of one's design skills: from testing, to object-design, design patterns, principles, refactoring, and architecture. A lot of musicians I know tend to spend a lot of money on expensive equipment like instruments, speakers, programs, pedals, and all kinds of other fun things — sometimes to ridiculous proportions. When it comes to doing a good job in any trade, tools matter for sure, but I think it's more about the technique. I've heard, in my opinion, some of the most engaging music created by folks that had nothing but a tape recorder and a couple of instruments. Perhaps that's why Grammy award-winner and Rock & Roll Hall of Fame-r, Trent Reznor, decided to forgo his nearly multi-million dollar studio for a laptop with some basic programs on it to create a record that became the band's first number-one album on the Canadian Albums Chart over a career of 25 years. In this trade of software design, if you're serious about mastering it, I believe that TDD is the vital technique that will take you there. TDD has many benefits, but one major aspect is that it creates a scenario where we can integrate everything we've learned (and will learn) about design — all the wisdom of principles, rules, patterns, and what we've learned makes for testable, flexible, and maintainable code — in a safe, risk averse way. Chapter goals In this chapter, we will: Formally discuss test-driven development and the rules and schools of thought to TDD. Recap critical prerequisites in order to use TDD to develop a web application and discuss what makes TDD hard to perform in the real-world and Explain how we use both the Mockist (London-style) and Classic (Boston-style) TDD schools of thought to implement Double Loop TDD. Learn how to rely on our testing strategy to increase confidence in our codebase after we've finished the Acceptance Test. Learn why you should be refactoring constantly and why the refactor step of the TDD loop is the key place where design happens Wrap up Phronesis and grasp how the remaining parts of the book integrate back into the phronimos techniques we've covered Test-Driven Development rules & considerations Red-Green-Refactor As you know, TDD (test-driven development), is a technique — or a process — for developing software. The goal is to keep code quality high and keep you productive, even as projects grow to be really large and complex. It works by following the red-green-refactor loop: Red — Write a failing test Green — Write just enough code that will pass the failing test Refactor — Criticize the design and refactor the code, keeping the tests intact /book-assets/Software Design and Architecture Wiki 16ec9c6a09b3410ca7be7920be75e128/Part III Phronesis 60b174f15da34fdcb5bc8a099436a9bb/28%20Test-Driven%20Development%20Workflow%204c7242c35e4246558f4fa70e0fef1f68/Untitled.png This is a technique that can replicated and followed along with. When you're writing the failing test, you're focusing on making sure that the test makes sense and that you understand how you'll be able to write the solution how to prove that that solution is correct. If we have no idea how we'll make the test pass, we learn that right away. TDD gives us immediate consequence detection at each step. Don't get ahead of yourself (the three laws of TDD) Some equally important TDD rules to follow are: 1. You are not allowed to write any production code unless it is to make a failing test pass Because it is so much harder to write tests after the code has been written, the idea is to start with the tests. 2. You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures. Your goal is to use the tests to drive the design. When you write your first test, you'll often refer to things that don't quite yet exist. Here's an example: If I did nothing other than just wrote those lines of code, then my code would not be compiling. The rule says to merely make the code compile — so this means to create the class, give it a method and a enum object so that this code will compile. But do nothing more. The test will fail, but the code will pass. You're in red mode. 3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test Once you make the failing test pass, STOP. Don't write any more code. Stop. Take a moment to contemplate your design since you've moved from red to green and now you're in refactor. Once you…
Part I: Up to Speed
Part I: Up to Speed 💡 Programming is the art of telling another human what we want the computer to do. More specifically, as paid tradespeople, our mission is to write testable, flexible, and maintainable code. How do we do this well? The last 40 years have introduced a number of influential movements (XP, Agile, Craftsmanship), programming techniques (TDD, Pair programming, CI/CD), and relied on the discovery of patterns and architecture styles (like DDD, layered architectures, etc) to develop testable, flexible, and maintainable software. Let’s gain awareness. It’s time to get up to speed on the world of software design. Continue reading 1. Complexity & the World of Software Design 2. Software Craftsmanship 3. A 5000ft View of Software Design
45. The Creational Principles
45. The Creational Principles 💡 Creational principles address the question of when and how we introduce new abstractions, aiming to prevent code bloat, reduce duplication, and keep things minimal. Tools like TDD (test-driven development) and object calisthenics can act as triggers for factoring out classes or methods at the right time, rather than too early or too late. Chapter Goals Explore four creational guidelines. Understand real-life eCommerce contexts (like discount logic, user profiles) where these principles shine. Connect TDD and object calisthenics to each principle, ensuring we create abstractions at the right moment. DRY / The Rule of Three This one ain’t new. Definition: Don’t Repeat Yourself. If you see the same logic or code pop up in three places, refactor it into a single place. Problem Solved Reduces duplication that leads to inconsistent changes or “fix bugs in one place but forget to fix in another.” Minimizes guesswork or code scattering. If a discount formula changes, you only update it once. Realistic eCommerce Example: Discount Logic Imagine an online store that calculates special “Black Friday” discounts. You accidentally wrote the discount formula in three separate controllers: a CartController, an OrderController, and a CheckoutService. Ha. That’s a recipe for duplication trouble. TDD / Object Calisthenics Note TDD: If you keep re-writing the same test logic for discount in multiple test files, that’s a sign you might unify the code. Object Calisthenics: Watch for repeated conditionals or calculations in more than two places. That’s a “Rule of Three” clue to unify them. YAGNI Definition: You Aren’t Gonna Need It. Don’t build functionality until you see a real requirement for it. Problem Solved Prevents over-engineered features that might never be used. Keeps your code minimal and straightforward. Realistic eCommerce Example: User Class Without Extra Junk TDD / Object Calisthenics Note TDD: If your tests never require , it’s a sign you might not need that method yet. Object Calisthenics: If a class has more than two instance variables or multiple public methods you never call, it might be YAGNI violating. Remove them until demanded. DDD Tip: This is actually how we lead to big aggregates. If we add too many properties to a write object (an aggregate), it could slow down our ability to load them quickly. That’s no bueno. That’s why it’s so good to start at the end and focus on what you actually need (see Programming By Wishful Thinking). KISS (Keep It Simple, Silly) Definition: Keep solutions as simple and straightforward as possible, avoiding unnecessary cleverness or layering. Problem Solved Complexity kills agility. Readers shouldn’t puzzle over complicated flows for a basic feature. Realistic eCommerce Example: Factorial vs. Product Calculation? Where might this apply? Maybe you do a “bulk discount” that uses a factorial-based formula (though that’s odd!). KISS says keep the formula straightforward and maintainable. TDD / Object Calisthenics Note TDD: Overly clever solutions often lead to more complex test setups. If your tests are becoming complicated, see if you can revert to simpler logic. Object Calisthenics: “No classes with more than two instance variables” might push you to avoid jam-packing a utility class with many half-baked methods. Programming by Wishful Thinking We’ve also covered this one before in TDD. Principle: Write code as if the “ideal methods or classes” already exist, letting usage define a clean interface. Then implement them. Problem Solved Encourages a “client’s perspective” approach. You shape your API around what you want it to do, not how it’s currently done. Realistic eCommerce Example: Order Processing Why it helps: You avoid accidental complexity by focusing on the simplest interface that meets the scenario’s needs. TDD / Object Calisthenics Note TDD: You might write a test that calls , then implement after. Object Calisthenics: If “process” ends up handling multiple concerns, that’s a sign we might break it into “reserveInventory() + chargePayment() + notify()” or introduce a “Coordinator” object. Summary Creational principles guide us on when to introduce new abstractions, ensuring we don’t over- or under-engineer: DRY / Rule of Three – Once you see duplication thrice, unify it. YAGNI – Don’t build what you don’t actually need right now. KISS – Keep logic straightforward and minimal. Programming by Wishful Thinking – Let usage shape a clean interface; fill in details after. With these in mind—and the help of TDD and object calisthenics to sense friction or duplication—you maintain an evolving codebase that’s testable, concise, and exactly as complex as the current requirements demand, no more. Continue reading 46. The Least Principles
13. Features (use-cases) are the key
13. Features (use-cases) are the key 💡 A feature-first (or use-case-driven) approach to software development is, arguably, the best way to write testable, flexible, and maintainable code. To focus on the features (the use cases) is to focus on the essential complexity. Such an intentional approach to software development improves virtually every aspect of our work: from planning to architecture, testing, design, and beyond. The way our industry's organized, for newer developers, it's almost as if we enter real software development projects flying by the seat of our pants. It's as if we're learning to fly a plane that's already ten thousand feet into the air. We sometimes treat greenfield projects like experiments. Now, don't get me wrong, experiments are good, but when there's a customer behind us paying good money to see their project come to fruition, I don't think it's ethical to be running experiments. If there's anything we know to be true about experiments, it's that they may very well fail. I don't know about you, but nothing else gives me imposter syndrome quite like not knowing if I'm carrying out my work similarly to the way a professional would. I've been there many times. I was there when I joined a consultancy as a freshly graduated over-confident junior developer. I wanted to prove my worth at my first gig. Without a mentor or.much knowledge of principles and software development processes, my outlook on coding was that "coding is just typing". If the user stories looked like they worked, I was golden. And if there were bugs, I'd just add more code until there weren't. The way I learned I messed up was getting called back into the office to re-fix bugs or re-implement features after embarrassing customer disappointments. Yikes! I also had the same nervous, terrible gut feeling when I dived into my first contract gig, gave the customer a fixed price, built out what I believed worked, and then proceeded to write untested bugs in text files. When the angry client called me and told me that code didn't work, I had to bite the bullet, come back, and right my wrong with several hours of free work to fix those bugs. As modern software craftspeople, there's a lot to learn from planning, dealing with customers, making sure that your code will work, and feeling confident about it. There a lot of different ways to develop software, yes — but to produce testable, flexible, and maintainable code all while under time and cost constraints is something of a feat. If someone said they knew how to do that, I'd pay close attention. This is evidently what drew me to XP. We briefly discussed Agile and the concept of XP: Extreme Programming in Part I: Up to Speed. To remind you, XP is a mixture of business and technical practices. It is a relatively standard approach that claims it can consistently lead us to well-crafted code and happy customers. XP is our starting point for obtaining the knowledge and confidence to do the right thing. Know the right thing and be doing the right thing, regardless of how you feel about it. After several months of research, conversations with developers online, and reading books written by our phronimos (expert) developers, I've compiled a plan. What you'll find in the following pages of Part III is a condensed version of the most effective principles, practices, and patterns used by professional software developers. This section of the book introduces us, at a high level, to all of the other topics we aim to master throughout the rest of the book. In Part III, we'll learn how the phronimos software developers work from start to finish. Specifically, you'll learn a philosophy for software design which helps us answer the following questions: How do we scope a project? How do we kick off a project? What's the best way to learn the domain? What's the best way to extract the requirements from the customer? How do we give good estimates? How do we keep the customer happy (so that they keep paying us)? How do we balance power between the customer and us? What should the customer have a say over, and what should we have the final say over? Just how involved should the customer be throughout the project? What happens if we can't meet the deadlines? How do we develop the initial project structure (the architecture)? How do we decide what constitutes good architecture? Should we account for the time it takes to get things set up? When does actual design happen? How do we prevent bugs and regressions in the codebase? How do we effectively test the requirements? Should we use mocks? Why or why not? What do we do about non-functional requirements? How do we discover them? How do we test them? How do we keep our code flexible and maintainable? How do we know when we're done? Regardless of if you're a freelance developer, you work at a consultancy, a startup, or you're building your own startup company, I think you'll find something of value here. In this first chapter of Phronesis, I want to…
21. Understanding a Story
21. Understanding a Story 💡 We interview the customer or domain expert to uncover the entirety of the essential complexity for a feature. With pseudocode, we turn our vague understanding into a detailed one that can be broken into smaller parts, understood by the customer, and eventually acceptance tested. It's true. Every customer is out there to make your life a little bit more miserable by tossing in additional requirements just as you thought you were done implementing a feature. In case you couldn't tell, that was sarcasm. But that doesn't change the fact that this still does seem to happen. "The requirements are always changing!" I can hear the complaining in already. Here's a perspective-shifting question: what if the requirements that tend to crop up towards the tail end of implementing a feature were actually always there? What if they never changed? What if it was just that we never discovered them? Of course, both scenarios happen. We sometimes miss requirements and they sometimes get tacked on later once the business uncovers new information. However, at this stage of our feature-development journey, expect your current understanding of a feature to be pretty vague. We should not touch code yet. If we've done Event Modelling or Event Storming, all we know is the command/event pair and the subdomain (or bounded context — we discuss this later, as it pertains to how we physically package the application). At this stage, we don't yet know the details. The complete details, if you'll recall from 13. Features (use-cases) are the key, are the data, behavior, and namespace — and we're missing the first two. Now is the time to uncover as much of the inherent essential complexity that exists as possible. There may be a lot of it. That's okay. Our goal at this step is to merely shine a light on it. When it comes to complexity: elucidate the essential, avoid the accidental In this chapter, we'll discuss how to learn and document the essence of a story in a way that the customer can understand and check, that can be almost seamlessly translated to code, and that is void of unnecessary technical details. After this, we'll feel confident enough to break the story into smaller parts and get to building out the feature. Chapter goals Specifically, in this chapter, we will: Learn good principles for interviewing a domain expert Learn how to document the essential complexity of a feature with pseudocode Interviewing a domain expert In 20. Iteration Planning, we discussed a few different ways to learn the details of a story. The most common approach I've seen is the where someone writes down the requirements and hands it to the developers. It's usually a ticket — a story with written details — created in a project management tool like Jira or Asana. In this scenario, the story details are written by someone known to XP practitioners as the requirements jockey (be it the project manager, the engineering manager, or some other representative for the customer) and contain a good amount of detail and resources including mockups of the screens and a number of scenarios that need to work. Regardless of the approach we use, what's important is that we get time to interview the domain expert and ask them questions to clarify. Preferably face-to-face or over a video call. Also remember that the customer/domain expert could be one person but it could also be a number of people (see 15. Customers). "But domain experts are busy!" Yes, but since stories are such small slices of functionality, interviews can be very quick. It should take anywhere from 15 to 30 minutes, and rarely longer than an hour. Rules for a good interview To conduct a good interview, there are a few rules the DDD community recommends. The first is to listen and ask questions more than you speak. We're here to learn about the story from the domain expert's point of view because that's ultimately what goes into production. The second is to avoid jumping to technical conclusions. Rejecting technical conclusions means doing what we talked about in 13. Features (use-cases) are the key, forgetting the fact that you normally start building features and projects database-first, API-first, or class-first. When we think this way, we end up corrupting the domain with unnecessary technical details and make things harder for ourselves in the long-run. Domain-driven design is persistence ignorant, technology ignorant, and as we'll discuss in an upcoming chapter (23. Programming Paradigms), paradigm-ignorant. We'll learn how to document the essence purely. The last is to avoid the use of technical language. Domain experts don't know what floats or observables are. Remember who you're talking to and try to speak in their language, the ubiquitous one. Documenting with pseudocode As we interview the domain expert, we'll want to document what we're learning, but not using traditional methods like UML, use-case diagrams and other formal documents that are expensive…
32. Why & How to Learn Object-Oriented Software Design
32. Why & How to Learn Object-Oriented Software Design 💡 Much of design is about structure and relationships — the essence of the object-oriented paradigm. By learning OO properly, we remedy many frustrating design challenges faced by both front-end and back-end developers. OO design skills significantly increase our confidence to take on more ambitious projects. In the late 2000s, at the time, Kobe Bryant was undeniably known as the best basketball player in the world. Among his incredible list of achievements included: Taking the Lakers to win three consecutive NBA championships. Leading the NBA in scoring from 2005-06. Knocking out a whopping 81 points against my home team, the Toronto Raptors (ouch) — the second-highest number of points ever scored in a game in the history of the NBA. What was the key to Bryant's greatness? Was it that he studied the greats? Was it that he knew the flashiest moves? No. It was where he put his awareness — his energy, his focus. Sports trainer Alan Stein, Jr., once shared that Bryant would rigorously practice "the most basic footwork in offensive moves" — the type of stuff Alan "routinely taught to middle school-age players." When asked why he was practicing the basics over and over, Bryant smiled and replied with all seriousness, "Why do you think I'm the best in the world? Because I never get bored with the basics." Getting lost in the sea of new tools, technologies, languages, frameworks, and libraries is easy. While it's ideal to stay up to date, if we'd like to be good at what we do, we shouldn't consider ourselves exempt from the basics. We must put in reps. Alright, then. What are these basics of which you speak, Khalil? To spin up a REST API? Implement the quicksort algorithm? Some recursive magic? There are many different ways to answer this. But if there's one thing I know for sure, OO — the most widespread programming paradigm — is a significant part of the basics, and we shouldn't neglect it. OO teaches us much about design, whether you continue using it or not. We can't deny this. In today's programming climate, you must know how it works and how to use it effectively; only then can you understand what you're leaving behind when you pursue the purely functional approach. Look. I know you've probably studied object-oriented programming in school. You're probably at the very least aware of concepts like polymorphism, encapsulation, and inheritance (curse those terrible animal-dog examples). Now, if you're similar to me, whatever you've learned hasn't been tremendously helpful in practice. Perhaps, you're still nervous about when to use that keyword. Or maybe you're one of the thousands of developers who feel that classes tend to get confusing and out of hand too quickly. It's also likely you're unsure about things like: When to use an interface or abstract class When to use an abstract method How to use mocks and stubs When not to use mocks and stubs And when to actually use inheritance and polymorphism For those that lack the OO basics, it's not uncommon to feel like you: Don't know how to structure things Don't know when to break files up Don't know where to put decision-making logic Have to constantly re-learn new ways to build when your favorite libraries or frameworks change their best practices Experience mass amounts of confusion and imposter syndrome making things that aren't web apps (games, robots, desktop applications, etc.) Struggle to handle cross-cutting concerns like routing and auth in front-end architectures Rely a lot on the frameworks, and when you get stuck, you're really stuck I'm sure this list barely scrapes the surface of problems you've likely faced or are currently facing. Well, forget the pain and suffering you've endured with object-oriented programming. Erase it from your mind. We're going to re-learn. Properly. The OO paradigm can teach us a lot about design. So let's dive deep into the skill that is Object Design. Chapter goals In this introductory chapter, we: Learn why tests aren't enough. Learn about Object Design and its parts: analysis, design, and programming. Discuss how learning object design affects your front-end or back-end development skills. Discuss a framework or learning path to object-oriented software design mastery. Current challenge: design In Part III: Phronesis, we saw how the object-oriented paradigm compared to the others in 23. Programming Paradigms. We even learned how 24. An Object-Oriented Architecture could work in practice. Then in Part IV: Test-Driven Development Basics, we learned how to use the classic TDD approach to watch our designs emerge — using **both “programming by wishful thinking” and the more linear Transformation Priority Premise techniques. This is a great baseline. At this point, you should feel confident about using tests to make functions and drive the design of classes that contain core code. There is a problem, though. While tests can guide our designs, they aren't a substitute…
May 11th, 2021 update
May 11th, 2021 update Had a very busy two weeks at Apollo GraphQL and admittedly, work on the book took was forced to take a bit of a back seat. Celebrating my birthday tomorrow then we're going to give it another go of the good 'ol college try. Shuffled some of the dates around. Let's see if I can work some magic. Part I — Up To Speed — Complete Part II — Humans & Code — Complete Part III — Phronesis by May 19th Part IV — Test-Driven Development Basics by May 26th Part V — Object-Oriented Design w/ Tests by June 7th Part VI — Design Principles by June 18th Part VII — Design Patterns by June 25th Part VIII — Architecture Essentials by July 2nd Part IX — Building Web Applications with Domain-Driven Design, Hexagonal Architecture, and CQRS by July 19th Part X — Advanced Test-Driven Development by Aug 3rd Conclusion, Introduction & Part XI — Above and beyond by Aug 15th Wrap-up — Aug 22nd
7. Documentation & Repositories
7. Documentation & Repositories 💡 A well-designed repository provides answers to the most common top-level developer goals and acts as the jumping-off point for learning how to work within a codebase. Design reminds me of when I used to play midfield in soccer. The midfielder needs to keep track of the game, has to be a couple of seconds ahead, and has to think about what's going to be required of them next. Midfielders often have to survey their surroundings, notice the positioning of your teammates, large gaps, and strategically place themselves in a position to be useful. Midfielders help strikers set up plays. They predict when the defensive line may need a little bit of support. To me, midfield is highly strategic, and it's about being a team player that knows how to create leverage. A well-designed code repository is very much similar. It creates leverage. Well-designed repositories account for the most common things that a new developer needs to know to become productive with the codebase. It's our first opportunity to create leverage, having the codebase answer questions for us instead of having to answer them over and over. And what happens when you're gone from the project? Will a future maintainer have questions? You probably don't want them hitting up your cellphone, do you? In this short chapter, we'll learn what's required to create high-leverage repositories. Chapter goals Learn the most common high-level goals a developer has on a new project Learn why tests can be used as a replacement to traditional API documentation for most enterprise software. Discuss how repositories are the first step in a constant endeavour to push complexity downwards. User goals and questions to address in a repository If I started a new job and just got access to the repository where my coworkers have been working, I'd want the repository to answer the following questions as succinctly as possible. What is this? — Is it the frontend application? The backend? Some other service? Give your repo a title and a description. The description should describe what the repo is for in a sentence. What is it for? — You'd be surprised at how many projects I've been asked to take a look at that I had no idea what they were for. This is helpful because it helps the developer build affordances — ah, this can be used for this problem that I'm having; got it! Ah, this makes this other problem easier, I see! Ah, so I can use this instead — sweet! How do I get started? — If you can get started in a few commands, make 'em copy-and-pastable How do I run the tests? — This should be able to be done in a single command. If it's a little more involved ****and you need to install a bunch of stuff, use a separate page and link to it as an install guide. How do I debug it? — If there are special things that need to be done to run in debug mode (like passing in some flags), make that known here. This is definitely a common thing to need to do. Where are the features? — Lastly, since we primarily work on features, if we're using a feature-driven folder structure, this will help to become productive even faster. Push complexity downwards Just like this book is organized with parts and chapters, you want to use push complexity downwards. In 6. Organizing things, we said that your feature folders are the place where we do work. Including a link or making it easy to find from your repository only improves discoverability. The layers of abstraction follow this hierarchy: Repository → feature folders → tests → implementation boundary (controller or page) → implementation internals Tests as documentation I've likely said it a few times already, but: Our tests will act as the primary form of documentation 90% of us are building enterprise applications and web apps to be primarily consumed by paying customers. For us, written API documentation may be more work than it's worth. For developer tooling teams and teams that maintain public SDKs, libraries, or frameworks (like Apollo or Stripe) — yes documentation is paramount. For everyone else, the most important thing is to learn the system's use cases, where they are in the code, and how to add, change, and remove them. Summary Use the repository to answer common questions The repository should link to the features, and feature contain tests which demonstrate the functionality — to learn how it works, readers can trace layers of abstractions into the implementation Tests act as our primary form of documentation Exercises 💡 Coming soon! Resources Articles https://devops.com/dont-make-code-affordances-developers/ Continue reading 8. Naming things
Technical Benefits
Technical Benefits There are huge payoffs to DDD and domain modeling. When our code lines up with the real-life domain, we end up with a rich declarative design that enables us to make changes and add new features exponentially faster. Projects that adopt DDD can expect the following technical benefits: Testable business-layer logic Less time fixing bugs A codebase that that improves rather than degrades over time as code gets added to it Long life-spans Continue reading Technical Drawbacks

November 16th update

Added a guide on Design Thinking

Design Thinking is the final topic in the developer mindset portion of the pillars of clean code.

In this guide, we learn about the basics of Human-Centered Design how you can use it to optimize your code to be understood by humans.

We're learn the psychology behind how humans discover and understand what can be done and how things work.

Then, we're learn the fundamental principles of design. Just like how there are software design principles, there are human-centered design principles. We can use them to optimize the discoverability and understandability of your code.

Armed with that knowledge, we'll be able to determine if code is clean and easy to work with, what makes it challenging to use, and how to improve it so that we can keep the developer experience of our coworkers and future maintainers high.

But Khalil, can't I just read Uncle Bob's "Clean Code"?

While I do recommend reading "Clean Code", this guide is going to act as a part of the philosophy — the baseline, behind how we reason about our own coding conventions. It will then act as a compliment to the rest of the structural software design principles we cover in this book.

Lastly, after having established the philosophy here, it will become possible for us to have principled and empathetic discussions towards balancing code that is structurally correct yet still understandable to humans.

Read the guide here.

📣 Submit feedback