Preface

What Is Tidy First?

“I have to change this code, but it’s messy. What should I do first?”

“Maybe I should tidy the code before I make the change. Maybe. Some. Or maybe not?”

These are questions you might ask yourself, and if there were easy answers, I wouldn’t have felt the need to write a book to address them.

Tidy First? describes:

  • When to tidy messy code before changing what it computes

  • How to tidy messy code safely and efficiently

  • How to stop tidying messy code

  • Why tidying works

Software design is an exercise in human relationships. In Tidy First? we start with the proverbial person in the mirror—​with the programmer’s relationship with themself. Why don’t we take time to care for ourselves? Take time to make our work easier? Why do we go down the rabbit hole of cleaning code to the exclusion of work that would help our users?

Tidy First? is the next step in my mission to help geeks feel safe in the world. It’s also the first step to take when faced with messy code. Software design is a powerful tool to ease pain in the world—​if it is used well. Used badly, it becomes just another instrument of oppression, and a drag on the effectiveness of software development.

Tidy First? is the first of a series of books focusing on software design. I want to make software design approachable and valued, so I’m starting with the kind of software design you can do on your own. Subsequent volumes will apply software design to heal relationships between the programmers on a team, and then address the biggie: the relationship between business and technology. But first, let’s understand and practice software design in ways that benefit our daily work.

Let’s say you have a big function containing many lines of code. Before changing it, you read that code to understand what is going on. In the process, you see how you can logically divide the code into smaller chunks. When you extract those chunks, you’re tidying. Other kinds of tidying include using guard clauses, explaining comments, and helper functions.

As a book, Tidy First? practices what it proposes—​delivering these tidyings in small chunks and suggesting when and where you might apply them. So, instead of trying to master tidying all at once, you can try out a few tidyings that make sense for your problem. Tidy First? also begins describing the theory behind software design: coupling, cohesion, discounted cash flows, and optionality.

Audience

This book is meant for programmers, lead developers, hands-on software architects, and technical managers. It is not tied to any programming language, and all developers will be able to read and apply the concepts in this book to their own projects. This book assumes that the reader is not new to programming in general.

What You Will Learn

By the end of this book, you will understand:

  • The fundamental difference between changes to the behavior of a system and changes to its structure

  • The enabling magic of alternating investment in structure and investment in behavior, as a lone programmer changing code

  • The basics of the theory of how software design works and the forces that act on it

And you will be able to:

  • Improve your own experience of programming by sometimes tidying first (and sometimes tidying after).

  • Begin to make large changes in small, safe steps.

  • Prepare to design as a human activity with diverging incentives.

Structure of the Book

Tidy First? is divided into an Introduction and three parts:

Introduction

I begin with a brief description of my motivations for writing this book, how I came to write it, who it’s intended for, and what you can expect. Then we dive right in.

Part I, “Tidyings”

A tidying is like a little baby miniature refactoring. Each short chapter is a tidying. If you see code like this, then change it to code like that. Then send it to production.

Part II, “Managing”

Next we cover managing the tidying process. Part of the tidying philosophy is that it should never be a big deal. It’s never something that has to be reported, tracked, planned, and scheduled. You need to change this code, and it’s hard to change because it’s messy, so you tidy first. Even as part of daily business, this is still a process that improves with thought.

Part III, “Theory”

Here’s where I finally get to spread my wings and dig deep into the topics that excite me. What do I mean by “software design is an exercise in human relationships”? Who are these humans? How are their needs better met with better software design? Why does software cost so damn much? What can we do about it (spoiler alert: software design)? Coupling? Cohesion? Power laws?

My goal is for readers to begin reading in the morning and be designing better that afternoon. Then designing a little better every day after that. Pretty soon software design will no longer be the weakest link in the chain of delivering value with software.

Why “Empirical” Software Design?

The loud debates in software design seem to be about what to design:

  • How big should services be?

  • How big should repositories be?

  • Events versus explicit service invocation.

  • Objects versus functions versus imperative code.

These what debates hide a more fundamental disagreement among software designers: when? Here’s a caricature of the poles of this disagreement:

Speculative design

We know what we want to do next, so let’s design for it today. It will be cheaper to design now. Besides, once the software is in production we will never have the chance to design, so let’s pile it all in today.

Reactive design

Features are all anyone cares about, so let’s design as little as we can today so we can get back to features. Only when features become nearly impossible to add will we begrudgingly improve the design, and then only just enough to get back to features.

I aspire to answer the question of “when?” with “somewhere in the middle.” When we observe that a certain class of features is hard to add, we design until the pressure is relieved. We start with just enough design to get the feedback cycles going:

Features

What do users want?

Design

How can programmers best be supported to deliver those features?

The empirical software design answer to the question of when is contingent. Design some time around when you can take advantage of the design. Answering this question requires taste, negotiation, and judgment. Is requiring taste and judgment a weakness? Sure, but it’s an inevitable weakness. Speculative and reactive design also require judgment, but they give software designers fewer tools to work with.

I like the word empirical to describe this style because it seems to clarify the distinction I’m making with speculative and reactive design timings. “Based on, concerned with, or verifiable by observation or experience rather than theory or pure logic.” Sounds about right.

How I Came to Write Tidy First?

As an undergraduate I took a course on software design that used the book Structured Design by Ed Yourdon (RIP) and Larry Constantine. I didn’t understand much of the book, mostly because I hadn’t yet encountered the problems it addressed.

Fast-forward 25 years to 2005. I had designed a bunch of software by this time. I felt like I had a pretty good grasp on design. Stephen Fraser organized a panel at OOPSLA (the big object-oriented programming conference) to celebrate the 30th anniversary of the publication of the book. Ed and Larry were to be on the panel, along with Rebecca Wirfs-Brock, Grady Booch, Steve McConnell, and Brian Henderson-Sellers.

If I didn’t want to get blown off the stage, I had some homework to do. So I cracked open my yellowing copy of Structured Design and started reading. Hours later I looked up, absolutely enthralled. Here were Newton’s laws of motion, but for software design. It was all so clear when it came out. How did we as an industry forget that clarity?

I remember the panel going well. A highlight of the conference was breakfast with Ed and Larry, two extremely bright guys completely comfortable with themselves and each other. Figure P-1 shows the signatures they left in my textbook long ago.

tifi 0001
Figure P-1. Inscriptions by Ed Yourdon (“Don’t believe anything you read in this book!”) and Larry Constantine (“…​including the above!”)

The book was showing its age by that time. Examples using paper tape and magnetic tape were no longer relevant. Nor was the discussion of assembly language versus the new higher-level languages. The basics, though, were spot on. I vowed that I would bring that material to today’s audience.

I made several abortive attempts to write a software design book in the intervening years (search for “Kent Beck Responsive Design” if you want to see what I was up to). It wasn’t until 2019 that I unexpectedly had two weeks of completely unscheduled time. I decided to see how much of the book I could write in those two weeks.

Ten thousand words later, I had learned an important lesson—​I wasn’t going to be able to tackle all of software design in one book. One scenario that kept coming up in what I had drafted was this moment of small-scale design: I have some messy code—​do I change it or do I tidy it first?

My book-writing experience has always been like this. Take a topic that seems too small for a book. Write. Discover the topic is way too large for a book. Take a tiny, too-small slice. Write. Discover the slice is too large. Repeat.

And so here you hold (virtually or for real) the first fruits of that now nearly 20-year-old vow. I found that in discussing that hourly question, “Should I tidy first?” I have been able to touch on many of the topics dear to my designer heart. I look forward to your feedback and to continuing to deepen my understanding of all that makes software design fun and valuable.

O’Reilly Online Learning

Note

For more than 40 years, O’Reilly Media has provided technology and business training, knowledge, and insight to help companies succeed.

Our unique network of experts and innovators share their knowledge and expertise through books, articles, and our online learning platform. O’Reilly’s online learning platform gives you on-demand access to live training courses, in-depth learning paths, interactive coding environments, and a vast collection of text and video from O’Reilly and 200+ other publishers. For more information, visit https://oreilly.com.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at https://oreil.ly/tidy-first.

Email to comment or ask technical questions about this book.

For news and information about our books and courses, visit https://oreilly.com.

Find us on LinkedIn: https://linkedin.com/company/oreilly-media

Follow us on Twitter: https://twitter.com/oreillymedia

Watch us on YouTube: https://youtube.com/oreillymedia

Acknowledgments

The “author” of a book is an accounting fiction. I typed the words, but these words wouldn’t be in your hands without a host of people. Here are some.

Thanks for early technical feedback to Anna Goodman, Matan Zruya, Jeff Carbonella, David Haley, Kelly Sutton, and the rest of my students at Gusto. Thanks for technical feedback on the manuscript to Maude Lemaire, Rebecca Wirfs-Brock, Vlad Khononov, and Oleksii Torunov. Thanks to my paying subscribers on https://tidyfirst.substack.com for giving me the gift of time to write and for their feedback on the chapters as I drafted them.

Thanks to the expert production team at O’Reilly, who made the process as smooth as it can possibly be: Melissa Duffield, Michele Cronin, Louise Corrigan. Thanks to Tim O’Reilly for taking a chance on a short book.

Thanks to Keith Adams and Pamela Vagata for technical talk, encouragement, and the occasional cocktail. Thanks to Susan for the right mix of encouragement and nudging. Thanks to my children, Beth, Lincoln, Lindsey, Forrest, and Joëlle.

Thanks to my software design mentors and colleagues: Ward Cunningham, Martin Fowler, Ron Jeffries, Erich Gamma, David Saff, and Massimo Arnoldi.

Finally, thanks to Ed Yourdan (of blessed memory) and Larry Constantine for figuring all this stuff out so long ago.