Code Simplicity

Chapter 4. Change

Now that we understand the importance of the future, and that there are some things we don’t and can’t know about it, what can we know about it?

Well, one thing you can be sure of is that as time goes on, the environment around your software is going to change. Nothing stays the same forever. This means that your software will have to change in order to adapt to the environment around it.

This gives us the Law of Change:

• The longer your program exists, the more probable it is that any piece of it will have to change.

As you go into an infinite future, you start tending toward a 100% probability that every single piece of your program will have to change. In the next five minutes, probably no part of your program will have to change. In the next 10 days, a small piece of it might. In the next 20 years, probably a majority of it (if not all of it) will have to change.

It’s hard to predict exactly what will change, and why. Maybe you wrote a program for 4-wheeled cars, but in the future everybody will drive 18-wheel trucks. Maybe you wrote a program for high school students, but high school education will get so bad that the students can’t understand it anymore.

The point is, you don’t have to try to predict what will change; you just need to know that things will change. Write your software so that it’s as flexible as reasonably possible, and you’ll be able to adapt to whatever future changes do come along.

Change in a Real-World Program

Let’s look at some data on how a real-world program changed over time. There are hundreds of files in this particular program, but the details for each file won’t fit on this page, so four files have been chosen as examples. Details on these files are given in Table 4-1.

Table 4-1. Changes in files over time

	File 1	File 2	File 3	File 4
Period analyzed	5 years, 2 months	8 years, 3 months	13 years, 3 months	13 years, 4 months
Lines originally	423	192	227	309
Unchanged lines	271	101	4	8
Lines now	664	948	388	414
Grew by	241	756	161	105
Times changed	47	99	194	459
Lines added	396	1,026	913	3,828
Lines deleted	155	270	752	3,723
Lines modified	124	413	1,382	3,556
Total changes	675	1,709	3,047	11,107
Change ratio	1.6x	8.9x	13x	36x

In this table:

Period analyzed

The time period over which the file existed.

Lines originally

How many lines were in the file when it was originally written.

Unchanged lines

How many lines are the same now as they were when the file was originally written.

Lines now

How many lines there are in the file now, at the end of the analysis period.

Grew by

The difference between “Lines now” and “Lines originally.”

Times changed

The total number of times a programmer made some set of changes to the file (where one set of changes involves changes to many lines). Usually one set of changes will represent one bug fix, one new feature, etc.

Lines added

How many times, over the history of the file, a new line was added.

Lines deleted

How many times, over the history of the file, an existing line was deleted.

Lines modified

How many times, over the history of the file, an existing line was changed (but not newly added or deleted).

Total changes

The sum of the “Lines added,” “Lines deleted,” and “Lines modified” counts for that file.

Change ratio

How much larger “Total changes” is than “Lines originally.”

When we refer to “lines” in the above descriptions, that includes every line in the files: code, comments, documentation, and empty lines. If you were to do the analysis without counting comments, documentation, and empty lines, one major difference you would see is that the “Unchanged lines” count would become much smaller in proportion to the other numbers. (In other words, the unchanged lines are nearly always comments, documentation, or empty lines.)

The most important thing to realize from this table is that a lot of change happens in a software project. It becomes more and more likely that any particular line of code will change as time goes on, but you can’t predict exactly what is going to change, when it’s going to change, or how much it will have to change. Each of these four files changed in very different ways (you can see this even just looking at the numbers), but they all changed a significant amount.

There are a few other interesting things about the numbers, as well:

• Looking at the change ratio, we see that more work was put into changing each file than writing it originally. Obviously, line counts aren’t a perfect estimate of how much work was actually done, but they do give us a general idea. Sometimes the ratio is huge—for example, file 4 had 36 times as many total changes as it did original lines.

• The number of unchanged lines in each file is small compared to its “Lines originally” count, and even smaller compared to its “Lines now” count.

• A lot of change can happen to a file even if it only gets a little bit bigger over time. For example, file 3 grew by only 161 lines over 13 years, but during that time the total changes count reached 3,047 lines.

• The total changes count is always larger than the lines now count. In other words, you’re more likely to have changed a line in a file than to have a line in a file, once the file has been around for long enough.

• In file 3, the number of lines modified is larger than the number of lines in the original file plus the number of lines added. That file’s lines have been modified more often than new lines have been added. In other words, some lines of that file have changed over and over. This is common on projects with a long lifetime.

The above points aren’t all that could be learned here—there is a lot more interesting analysis that could be done on these numbers. You’re encouraged to dig into this data (or work out similar numbers for your own project) and see what else you can learn.

Note

Another good learning experience is looking over the history of changes made to one particular file. If you have a record of every change made to files in your program, and you have one file that’s been around for a long time, try looking at each change made over its lifetime. Think about if you could have predicted that change when the file was originally written, and consider whether the file could have been better written originally to make the changes simpler. Generally, try to understand each change and see if you can learn anything new about software development from doing so.

The Three Flaws

There are three broad mistakes that software designers make when attempting to cope with the Law of Change, listed here in order of how common they are:

1. Writing code that isn’t needed

2. Not making the code easy to change

3. Being too generic

Writing Code That Isn’t Needed

There is a popular rule in software design today called “You Ain’t Gonna Need It,” or YAGNI for short. Essentially, this rule states that you shouldn’t write code before you actually need it. It’s a good rule, but it’s misnamed. You actually might need the code in the future, but since you can’t predict the future you don’t know how the code needs to work yet. If you write it now, before you need it, you’re going to have to redesign it for your real needs once you actually start using it. So save yourself that redesign time, and simply wait until you need the code before you write it.

Another risk of writing code before you need it is that unused code tends to develop “bit rot.” Since the code never runs, it might slowly become out of sync with the rest of your system and thus develop bugs, and you’ll never know. Then, when you start to use it, you’ll have to spend time debugging it. Or, even worse, you might trust the never-before-used code and not check it, and it may cause bugs for users. In fact, the rule here should actually be expanded to read:

• Don’t write code until you actually need it, and remove any code that isn’t being used.

That is, you should also get rid of any code that is no longer needed. You can always add it back later if it becomes needed again.

There are lots of reasons people think that they should write code before it’s needed, or keep around code that isn’t being used. First off, some people believe they can get around the Law of Change by programming every feature that any user could ever possibly need, right now. Then, they think, the program won’t have to be changed or improved in the future. But this is wrong. It’s not possible to write a system that will never change, as long as that system continues to have users.

Others believe that they are saving themselves time in the future by doing some extra work now. In some cases that philosophy works, but not when you’re writing code that isn’t needed. Even if that code ends up being needed in the future, you will almost certainly have to spend time redesigning it, so you’re actually wasting time.

Writing Unnecessary Code: A Real-World Example

Once upon a time, a developer—let’s call him Max (ahem)—mistakenly thought he could ignore this rule. In his program, there were drop-down boxes where users could pick a value. Every company that used the program could customize the list of choices displayed in each drop-down box. Some companies might want the choices to be names of colors. Others might want them to be names of cities. They could be anything. So, the list of valid choices needed to be stored somewhere that each company could modify it.

The obvious thing to do was just to store the list of values, and nothing else. After all, that’s all that was needed. But Max decided to store two things: the list of values, and also information about whether each value was currently “active”—that is, if users could currently select that value, or if it was temporarily disabled.

However, Max never wrote any code to actually use the information about whether or not each field was active. All choices were active, all the time, no matter what the stored data said. He was sure that he was just about to write code to use the “active” information, though—maybe even tomorrow.

Several years passed, and the code to handle the “active” data didn’t get written. Instead, the data just sat there, unused, confusing people and causing bugs. Numerous customers and developers wrote to Max, wondering why nothing happened when they manually edited the list of values and set choices as being inactive. One developer improperly assumed that the “active” field was in use and wrote a piece of code that used it, even though the rest of the system didn’t use it. This got through to customers, and they started reporting strange bugs that took a lot of work to track down.

Eventually, some developer came along and said, “Today I will implement the ability to disable choices!” However, he discovered that the “active” field wasn’t designed perfectly for his needs, so he had to do a fair bit of redesign work to implement his feature.

Net result: several bugs, lots of confusion, and extra work for the developer who did eventually actually need the code. And this was a relatively minor violation of the rule! Severe violations can have considerably worse consequences, including missed deadlines, major catastrophes, and possibly even the destruction of your software project.

Not Making the Code Easy to Change

One of the great killers of software projects is what we call “rigid design.” This when a programmer designs code in a way that is difficult to change. There are two ways to get a rigid design:

1. Make too many assumptions about the future.

2. Write code without enough design.

Example: Making Too Many Assumptions About the Future

A government agency—let’s call it The Veteran’s Hospital—wants to make a program. We’ll call this program “The Healthcare System.” Before making this system, it decides to write a document stating exactly how the entire system should be implemented. It spends a year writing this document, making every single decision about the entire system during this time.

The developers then spend three years writing the system according to this document. As they work, they discover that the design in the document is contradictory, incomplete, and hard to implement. But the Hospital took an entire year to write it—the developers can’t wait another year to have it revised. So they implement the system, following the document as closely as they can.

The system is completed and given to the users for the first time. However, the situation at the Hospital has changed dramatically in the last four years, and when the users start actually using The Healthcare System, they realize they want something completely different. But the system is made up of hundreds of thousands of lines of code, all designed rigidly according to the document—it simply can’t be changed without months or years of effort.

So the Hospital starts writing a new document for a new system, and the process starts all over again.

The Hospital’s mistake was attempting to predict the future. They assumed that whatever decisions they made in the document were valid for real users, and would continue to be valid when the system was completed. When the actual future arrived, it wasn’t at all like what they had predicted, and their system was a multimillion dollar failure.

A better solution would have been to specify just one feature, or a tiny set of features, and immediately ask the developers to implement it. Then there could have been a back-and-forth of communication and user testing as development occurred. When the first set of features was done and released, they could have worked on additional features, one at a time, until they eventually had a system that was well designed and fully served its users’ needs.

Example: Code Without Enough Design

A developer is asked to create a program that people can use to keep track of tasks they need to do. To create a new “task” in the system, users fill out a form with some information, like a short summary of the task and how far along they are on it. This stores data in a database. Then, they can make notes about their progress on the task as time goes on, and eventually note that they have completed the task.

There’s a field called “Status” that indicates how far along the user is in performing the task. The values for this field are “No Work Done,” “In Progress,” “On Hold,” and “Complete.” When the Status field has the value “No Work Done,” it can change only to “In Progress.” When the Status field is “In Progress,” it can change to “On Hold” or “Complete.” And when it is “Complete,” it can change only back to “In Progress.”

There are 10 other fields in this program with similar rules. They each contain some different piece of information about the task (for example, to whom it’s assigned, what its deadline is, and so on).

To implement these rules, the developer writes one very long, continuous piece of code with no structure, in a single file. He validates each field with custom code that is specific to that field. For example, every time he needs to check if the status is “Complete,” he literally writes the word “Complete” in the code. Also, the code is not written to be reusable. Where the program has similar fields, the developer cut-and-pastes code and then modifies it slightly for the new field.

The code works. The file is 3,000 lines long. It almost entirely lacks a design.

Several months later, this developer leaves the project.

A new developer comes along and is assigned to maintain this project. He quickly discovers that this code is hard to change—if he changes one part of it, he also has to change many other parts of it in the same way in order to keep it working. To make matters even worse, the various parts are scattered around with no explanation or logical system—you have to simply read the entire file every time you want to make a change.

Customers start asking for new features. At first, the new developer does his best to implement these new features. He adds even more code to this file. It ends up being 5,000 lines long.

Eventually, customers start asking for features that simply can’t be implemented with this design. They want to send in information about tasks by email, but this code only does it with a form. It’s all designed very specifically around how the form works—it would never work with email.

Competitors start appearing that can update tasks by email. The project starts to lose its customers.

The only reason that this project survives is that two developers spend an entire year redesigning just this file so that it can be easily changed. They do their best to keep up with other feature requests while they’re redesigning, but most of their time is spent on the redesign.^[5]

The rule used to avoid rigid design is:

• Code should be designed based on what you know now, not on what you think will happen in the future.

Design based only on your immediate, known requirements, without excluding the possibility of future requirements. If you know for a fact that you need the system to do X, and just X, then just design it to do X, right now. It might do other things that aren’t X in the future, and you should keep that in mind, but for now the system should just do X.

When designing like this, it also helps to keep your individual changes small. When you only have to make a small change, it’s easy to do some real design on it.

This isn’t to say that planning is bad. A certain amount of planning is very valuable in software design. But even if you don’t write out detailed plans, you’ll be fine as long as your changes are always small and your code stays easily adaptable for the unknown future.

Being Too Generic

When faced with the fact that their code will change in the future, some developers attempt to solve the problem by designing a solution so generic that (they believe) it will accommodate every possible future situation. We call this “overengineering.”

The dictionary defines overengineering as a combination of “over” (meaning “too much”) and “engineer” (meaning “design and build”). So, per the dictionary, it means designing or building too much for your situation.

Wait—designing or building too much? What’s “too much”? Isn’t design a good thing?

Well, yes, most projects could use more design, as we saw in Example: Code Without Enough Design. But once in a while, somebody really gets into it and just goes overboard—sort of like building an orbital laser to destroy an anthill. An orbital laser is an amazing engineering feat, but it costs an enormous amount of money, takes far too long to build, and is a maintenance nightmare. Can you imagine having to go up there and fix it when it breaks?

There are several other problems with overengineering:

1. You can’t predict the future, so no matter how generic your solution is, it will not be generic enough to satisfy the actual future requirements you will have.

2. When your code is too generic, it often doesn’t handle specifics very well from the user’s perspective. For example, say you design some code that treats all input the same—it’s all just bytes. Sometimes this code processes text, and sometimes it processes pictures, but all it knows is that it’s getting bytes. In a way, this is a good design: the code is simple, self-contained, small, etc.

   But then you make sure that no part of your code distinguishes between pictures and text. This is too generic. When the user passes in a bad picture, the error she gets is, “You passed in bad bytes.” It should have said, “You passed in a bad picture,” but your code is so generic that it can’t tell the user that. (There are lots of ways that generic code can fall short when put to specific uses; this is just an example.)

3. Being too generic involves writing a lot of code that isn’t needed, which brings us back to our first flaw.

In general, when your design makes things more complex instead of simplifying things, you’re overengineering. That orbital laser would hugely complicate the life of a person who just needed to destroy some anthills, whereas some simple ant poison would greatly simplify that person’s life by removing the ant problem (assuming it worked).

Being generic with the right things, in the right ways, can be the foundation of a successful software design. However, being too generic can be the cause of untold complexity, confusion, and maintenance effort. The rule for avoiding this flaw is similar to the rule for avoiding rigid designs:

• Be only as generic as you know you need to be right now.

Example: Being Too Generic

In one part of a certain program, the user filled out a form and the program sent several hundred emails. This part of the program was very slow. The user would submit the form and the program would sit there for a very long time, sending all the messages.

To make this faster, the developers decided to not send all of the emails immediately. Instead, they would be sent in the background after the user submitted the form, using a pre-existing piece of code called “Email Sender.”

The developer who started working on this change decided that some companies might want to use something other than Email Sender. He wrote hundreds of lines of code to allow customers to “plug in” other systems for doing background work. No customer had ever asked for this; the developer just predicted that somebody would want this specific sort of flexibility in the future.

Eventually, the Chief Architect of the program took over work on this change. He removed all of the code for “plugging in” other systems, because there was no evidence that users wanted it. Thus, there was no evidence that the code should be that generic right now. With those pieces removed, the change became much simpler.

Four years have passed since the change was originally made, and not a single customer has needed the ability to plug in other systems. There was, factually, no reason to be that generic.

Incremental Development and Design

There is a method of software development that avoids the three flaws by its very nature, called “incremental development and design.” It involves designing and building a system piece by piece, in order.

It is easiest to explain by example. Here’s how we would use it to develop a calculator program that needs to add, subtract, multiply, and divide:

1. Plan a system that does only addition and nothing else.

2. Implement that system.

3. Fix up the now-existing system’s design so that it is easy to add a subtraction feature.

4. Implement the subtraction feature in the system. Now we have a system that does only addition and subtraction, and nothing else.

5. Fix up the system’s design again so that it is easy to add a multiplication feature.

6. Implement the multiplication feature in the system. Now we have a system that does addition, subtraction, multiplication, and nothing else.

7. Fix up the system’s design again so that it is easy to add the division feature. (At this point, this should take little or no effort, because we already improved the design before implementing subtraction and multiplication.)

8. Implement the division feature in the system. Now we have the system we started out intending to build, with an excellent design that suits it well.

This method of development requires less time and less thought than planning the entire system up front and building it all at once. It may not be easy at first if you are used to other development methods, but it will become easy with practice.

The tricky part of using this method is deciding on the order of implementation. In general, you should pick whatever is simplest to work on at each step, when you get there. We picked addition first because it was the simplest of all four operations overall, and subtraction second because it logically built on addition in a very simple way. We could possibly have picked multiplication second, since multiplication is just the action of doing addition many times. The only thing we would not have picked second is division, because stepping from addition to division is too far of a logical jump—it’s too complex. On the other hand, stepping from multiplication to division at the end was really very simple, so that was a good choice.

Sometimes you may even need to take a single feature and break it down into many small, simple, logical steps so that it can be implemented easily.

This is actually a combination of two methods: one called “incremental development” and another called “incremental design.” Incremental development is a method of building up a whole system by doing work in small pieces. In our list, each step that started with “Implement” was part of the incremental development process. Incremental design is similarly a method of creating and improving the system’s design in small increments. Each step that started with “Fix up the system’s design” or “Plan” was part of the incremental design process.

Incremental development and design is not the only valid method of software development, but it is one that definitely prevents the three flaws outlined in the previous section.

---

^[5] This is the story of a file called process_bug.cgi from a product called “Bugzilla.” The story has been simplified somewhat from what actually happened, but the numbers (in terms of lines of code and the time it took to fix it) are roughly accurate. If you want to see the entire history of the redesign project to see how it was done, you can read the records listed here: https://bugzilla.mozilla.org/showdependencytree.cgi?id=367914&hide_resolved=0.