Readability of code depends primarily on how space is occupied by letters and symbols.

What does that mean? Well, it means two things:

Code should have the proper amount of white space around it. Not too much, not too little.

There should be the proper amount of space within a line of code to separate out the different parts. Separate actions should generally be on separate lines. Indentation should be used appropriately to group blocks of code.

With this principle, it’s actually the absence of code that makes things readable. This is a general principle of life–for example, if there was no space at all between letters and words in a book, it would be hard to read. On the other hand, it’s easy to see the moon against the clear night, because there’s a lot of clear black space that isn’t the moon. Similarly, when your code has the right amount of space in it, you can tell where and what the code is easily.

For example, this code is hard to read:

x=1+2;y=3+4;z=x+y;print"hello world";print"z is"+z;if(z>y+x){print"error";}

Whereas with the proper spacing in, around, and between the lines, it becomes easy to read:

x = 1 + 2;
y = 3 + 4;
z = x + y;
print "hello world";
print "z is" + z;
if (z > y + x) {
    print "error";
}

There can also be too much or wrong space, however. This code is also hard to read:

    x            =          1+        2;
y = 3            +4;

  z = x    +      y;
print    "hello world"         ;
 print "z is " + z;
if (z  >     y+x)
 {        print "error" ;
        }

Code itself should take up space in proportion to how much meaning it has.

Basically, tiny symbols that mean a lot make code hard to read. Very long names that don’t mean much also make code hard to read. The amount of meaning and the space taken up should be closely related to each other.

For example, this code is unreadable because the names are too small:

q = s(j, f, m);
p(q);

The space those names take up is very little compared to how much meaning they have. However, with appropriately-sized names, it becomes more apparent what that block of code is doing:

quarterly_total = sum(january, february, march);
print(quarterly_total);

On the other hand, if the names are too long compared to how much meaning they represent, then the code becomes hard to read again:

quarterly_total_for_company_x_in_2011_as_of_today = add_all_of_these_together_and_return_the_result(january_total_amount, february_total_amount, march_total_amount);
send_to_screen_and_dont_wait_for_user_to_respond(quarterly_total_for_company_x_in_2011_as_of_today);

This principle applies just as well to entire blocks of code as it does to individual names. We could replace the entire block of code above with a single function call:

print_quarterly_total();

And that is even more readable than any of the previous examples. Even though the name we used–print_quarterly_total–is a bit longer than our other names for things, that’s okay because it represents more meaning than other pieces of code do. In fact, it’s even more readable than our block of code was, by itself. Why is that? Because the code block took up a lot of space for, effectively, very little meaning, and the function takes up a more reasonable amount of space for the same meaning.

If a block of code takes up a lot of space but doesn’t actually have much meaning, then it’s a good candidate for refactoring. For example, here’s a block of code that handles some user input:

x_pressed = false;
y_pressed = false;
if (input == "x") {
    print "You pressed x!";
    x_pressed = true;
}
else if (input == "y") {
    if (not y_pressed) {
        print "You pressed y for the first time!";
        y_pressed = true;
        if (x_pressed) {
            print "You pressed x and then y!";
        }
    }
}

If that were our whole program, that would probably be readable enough. However, if this is within a lot of other code, we could make it more readable like this:

x_pressed = false;
y_pressed = false;
if (input == "x") {
    handle_x(x_pressed);
}
else if (input == "y") {
    handle_y(x_pressed, y_pressed);
}

And we could make it even more readable by reducing it to this:

handle_input(input);

Reading “handle_input” in the middle of our code is much easier than trying to read that whole first block, above, because “handle_input” is taking up the right amount of space, and the block is taking up too much space. Note, however, if we’d done something like h(input) instead, that would be confusing and unreadable because “h” is too short to properly tell us what the code is doing. Also, handle_this_input_and_figure_out_if_it_is_x_or_y_and_then_do_the_right_thing(input) would not only be annoying for a programmer to type, but would also make for unreadable code.

Naming Things

It was once said by a famous programmer that naming things was one of the hardest problems in computer science. These principles of readability give us some good clues on how to name things, though. Basically, the name of a variable, function, etc. should be long enough to fully communicate what it is or does, without being so long that it becomes hard to read.

It’s also important to think about how the function or variable is going to be used. Once we start putting it into lines of code, will it make those lines of code too long for how much meaning they actually have? For example, if you have a function that is only called once, on one line all by itself, with no other code in that line, then it can have a fairly long name. However, a function that you’re going to use frequently in complex expressions should probably have a name that is short (though still long enough to fully communicate what it does).

-Max

Comments: 24

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

1. It is more important to reduce the Effort of Maintenance than it is to reduce the Effort of Implementation.
2. The Effort of Maintenance is proportional to the complexity of the system.

And that is pretty much it. If all you knew about software design were those two principles and the purpose of software, you could evolve every other general principle of software development.

-Max

Comments: 8

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

• Potential Value of Implementation (V_i for short): How “valuable” could it be to implement this? For example, if we add something to the program that could directly prevent somebody from dying, that’s very valuable. If it simply might prevent a future typo in a single error message, that’s hardly valuable at all.

  The “value” can be for the end user or for other programmers. When we’re talking about design decisions that affect only code, and not the end user, flexibility is one of the major values–how important could this flexibility be?

  The potential value is separate from how likely it is that the situation will occur where you will need it. That’s the next issue.

• Probability of Value (P_v for short): What is the chance that this value will be, in fact, realized by an end user (for a feature or functional change) or by another developer (for some design decision)? If we’re adding in code flexibility to allow for potential contact with extraterrestrial apes, that’s not a very probable occurrence. If we’re adding in a feature that is immediately useful to every single user, that’s 100% probability. (The number of users that a feature will be useful to is also part of the Probability of Value.)
• Effort of Implementation (E_i for short): How hard will it be to implement this? This is a one-time cost–the immediate difficulty of performing the work required to create this thing the very first time. This would probably be measured in person-hours.
• Effort of Maintenance (E_m for short): How much effort will it require to maintain this in the future? (This includes any effort added to maintaining the entire program by implementing this.) Will this complicate maintenance for the whole system? This is an amount that increases over time. Similar to Effort of Implementation, this would be most likely measured in person-hours.

What we’re trying to determine is the Desirability Of Implementation (D for short). This answers the questions “Is this something we should do or not?” and “What should the priority of implementing this be?”

The simplest form of the equation is:

D = (P_v * V_i) / (E_i + E_m)

Or, in English:

The Desirability of Implementation is directly proportional to the Probability of Value and the Potential Value of Implementation, and inversely proportional to the total effort, consisting of the Effort of Implementation plus the Effort of Maintenance.

However, there is a critical factor missing from the simple form of this equation: time. What we actually want to know is the limit of this equation as time approaches infinity, and that gives us the true Desirability of Implementation. So let’s look at this from a logical standpoint:

The Effort of Implementation is a one-time cost, and never changes, so is mostly unaffected by time.

The Value of Implementation may increase or decrease over time, depending on the feature. It’s not predictable, and so we can assume for the sake of this equation that it is a static value that does not change with time (though if that’s not the case in your situation, keep this factor in mind as well). One could even consider that the Effort of Maintenance is actually “the effort required to maintain this exact level of Value,” so that the Value would indeed remain totally fixed over time.

The Probability of Value, being a probability, approaches 1 (100%) as time goes to infinity.

The Effort of Maintenance, being based on time, approaches infinity as time goes to infinity.

At first glance, that might sound as though design is hopeless, because maintenance becomes infinite effort–an amount that no Potential Value could surpass–and it seems like every possibility must be accounted for, because given infinite time the probability seems to indicate that every possibility will occur. Those are not true statements, though, because you have to think about the rate at which both of those items increase. If the fundamental effort of maintenance is very small, then even as time goes on, it will remain small. You could say that there is a “coefficient of maintenance” on any design decision or feature, and that that determines how rapidly maintenance effort will accumulate over time. As far as the Probability of Value goes, if it is a very tiny number, it may remain tiny until thousands or millions of years have passed–so if the Effort of Maintenance increases at a great rate, then it will easily outstrip the Probability of Value and the Desirability of Implementation will approach zero as time approaches infinity.

What this equation actually tells us is that the most important factors to balance, in terms of time, are probability of value vs. effort of maintenance. If the probability of value is high and the effort of maintenance is low, the desirability is then dependent only upon the Potential Value of Implementation vs. the Effort of Implementation–a decision that a product manager can easily make. If the probability of value is low and the effort of maintenance is high, the only justification for implementation would be a near-infinite Potential Value of Implementation.

This interestingly indicates why small improvements in programming languages and development frameworks result in such enormous changes in the resulting products–because tiny reductions in the Effort of Maintenance can make tremendous changes in the Desirability of Implementation. Features that otherwise would be thrown away by a product manager as impossible become part of the basic design plan. Polishing the UI becomes more desirable, because it requires less effort for both implementation and maintenance.

And finally, I think that this communicates most exactly and truthfully why simplicity is so important–because simplicity is what determines the “coefficient of maintenance” that I talked about above. The effort involved in maintaining simple code increases very slowly over time–sometimes so slowly that you never will have to put any maintenance effort into it in your lifetime.

There’s a lot more that could be said about this equation. What are your thoughts on it? Anybody have any ideas of how Value of Implementation could be numerically calculated, or if it might break down into a set of other numerically-calculable factors? Anything you have to say about it, I’m interested.

-Max

Comments: 24

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

Twitter’s just one of the many proofs that you don’t have to have lots of features to be successful. In fact, many successful apps have fewer features than their less-successful competitors.

Still, you’ve got to have some features. After all, it’d be pretty silly to be programming, otherwise. But how do you decide which features you should have? Is it just up to the Chief Architect’s intuition, or how many users demand that you give them “feature X”? Does whoever shouts the loudest in the development meeting get their feature implemented first?

Well, no, there is a way to decide whether or not you should implement a feature, and it comes out of one of our most basic principles: the purpose of software. This principle (that the purpose of software is “to help people”) isn’t just some fancy-sounding gibberish I made up to make myself happy–I wrote it because it’s something that can actually be really useful to think about in everyday programming, and this question of “Should we implement this feature?” gives us a great opportunity to show how it can be applied.

So, let’s say that the purpose of your software is “to help people learn to type,” and you have to decide, “Should we add New Feature X?” Well, here’s what you can ask yourself about the feature: “Does this help people learn to type?” Simple. If the answer is no, then you don’t implement the feature. Also, “Does this harm people learning to type, or get in the way of learning to type?” If it harms people more than it helps them, then it shouldn’t be implemented.

Now, quite often, you’ll find that you can’t really say whether or not a proposed feature actually helps your users (or helps them more than it hinders them). You can’t stand there with certainty and say, “Yes, this absolutely helps people learn to type.” In that case, just skip it. Don’t implement the feature. There are plenty of features out there in the world where you can be sure that it will help your users–implement those instead. Perhaps some more data will come along in time that will make your decision clearer about this uncertain feature, but until then, you don’t have to implement it. Just wait (or go collect data to make your decision easier).

This whole idea is also very handy for prioritizing features. You ask yourself, “Out of all these features, which ones will most help people learn to type?” That sounds perhaps like an overly-simple suggestion, but I think that for Bugzilla, if we really looked at all our requested features and said, “Which one of these will most help people track bugs?” we’d come up with a pretty good priority list, and probably have some interesting discussions, too.

The higher you set the bar for certainty on these questions, the fewer features you will have, and the simpler your application will be. That is, you could say, “We have to only be kinda certain it will help people,” and that’s your standard (or “bar”) for helpfulness. Or you could say, “We only implement features that we are totally certain will help people,” and you’d probably have an enormously simple and very well-designed application. But it’s a judgment call–sometimes it’s hard to get data, and you have to implement features that you’re only pretty sure will be helpful. That can be the right decision, though, sometimes–different situations require different solutions.

Overall, how you make these decisions is up to you. What really matters is that you ask the questions. That’s one of the keys to keeping your product focused, simple, and polished.

-Max

Comments: 5

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

Now, some people misunderstood me and said, “Oh, SAR is just another name for MVC.” No, I used MVC as an example of SAR, but SAR is a much, much broader concept than MVC–they are not comparable theories. MVC is a pattern for designing software, whereas SAR (or ISAR) is a statement of the three (or four) components that are present in all software.

The fascinating thing about SAR is that it applies not only to a whole program, but also to any piece of that program. A whole program has a Structure, just as a function or single line of code has a Structure. Same for Action and Results.

Here’s a little more about each of the pieces, and some examples to help explain:

Structure

Here are some examples of things that would be considered “Structure” for the whole program:

• The directory layout of your code.
• All of the classes and how they relate to each other.
• The structure (schema) of the database, if your program uses a database.

  Note here that the actual data in the database isn’t part of the Structure, though. If your program is producing the data and then sticking it into the database, then that’s part of the Result. If the data is sitting in the database and your program is supposed to process it, then that data is part of the Input.

Then an individual class (and I mean a “class” in the object-oriented sense) would also have a Structure:

• The names of methods in the class and the types/names of parameters that they take.
• The names and types of variables (member variables) in the class.

Whether or not a function (or variable) is private or public would also be part of the Structure, because Structure describes what something is (as opposed to what it does or produces), and “private” or “public” are words that describe what something is.

A Structure is sort of “the components of the program” or “the pieces you make the program out of.” Function names and types, variable names and types, classes–these things are all Structure.

Structure just “sits there.” It doesn’t do anything unless there’s some part of your program that uses it. For example, a method doesn’t call itself, it just sits there waiting to be called. A variable doesn’t put data into itself, it just sits there waiting for you to do something with it.

Action

The Action of a whole program is very easy to understand. A tax program “does taxes.” A calculator program “does math.”

An Action is always a verb of some sort. “Calculates.” “Fixes.” “Adds.” “Removes.” Those are actions. Usually they’re a little more descriptive and specific, though, like, “Calculates how much rainfall there will be in Africa next year,” or “Fixes broken hard drives.”

Inside of a class, the Action is the code inside of the methods. That’s all some sort of action–something going on, something happening. In many programming languages, you can also have code outside of any class or function–code that just runs when you start the program. That’s Action.

Results

Every program, every function, and every line of code has some effect. It produces some result.

A Result can always be talked about in the past tense–it’s something that has been done or created. “Calculated rainfall,” or “Fixed hard drives.” In a tax program, we’d call the Result either filed taxes or filled-out tax forms. As you can see, it sounds a lot like the Action, just completed.

You don’t have to describe a Result in the past tense, though. I’m just saying it always can be described that way. For example, in a calculator program, normally we’d call the Result of addition “the sum,” (not past-tense, just a noun) but you could also say that the Result is “added numbers” (which is past-tense). Same thing, just a different way of describing it.

Individual pieces of your program have Results, too. When you call a method or function, it has a very specific Result. It gives you back some data, or it causes some data to be changed.

Whatever your program (or any part of your program) produces, that’s the Result.

ISAR in a Single Line of Code

So, I said that SAR applies to a single line of code, but I didn’t give you any examples. So here’s a single line of code:

x = y + z

y and z in that line are part of the Structure. They’re variables that hold some data. To make an analogy: A jug is a structure that holds water. A variable is a structure that holds data.

The numbers that are stored inside y and z are the Input. That’s the data that we’re doing something with.

+ is an Action: “Add these two numbers.” = is also an Action: “Store the result in x.”

And, of course, the Result is the sum of y and z that gets stored in x. If y is 1 and z is 2, then the Result is the number 3, which gets stored in x. (Also note that x is a itself variable and thus also part of the Structure, but that’s getting pretty technical.)

Wrapping It Up

So anyhow, I hope that explains SAR a bit better. It’s a concept that applies to any kind of programming, whether you’re building a big application or just writing a single-line script. And it’s not something that you have to think about in-depth every time you write a piece of code, but it’s something that can help us analyze and understand a program, particularly when we’re looking at how we can improve its design.

-Max

Comments: 4

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

In the MVC sense, the Model is the Structure, the Controller is what does the Actions, and the View is the Result. I think the analogy (and the words) Structure, Action, and Results are more widely and accurately applicable to the operation of every program in existence, though, moreso than MVC, though MVC is a perfectly good way of looking at it for GUI applications.

Really, Structure, Action, and Results probably describes almost any machine in existence. A machine has some parts that don’t move, a framework–that’s the structure. Some parts move and do something–that motion is the action. And of course the machine produces something (otherwise we wouldn’t care much about it) so that’s the result.

Computer programs are unusual machines in that they can modify their own structure. However, it’s important that some part of the program be stable, that they “not move” in a logical sense. The way that object classes relate to each other, the names of methods and variables–these are all parts of the structure that usually don’t change while you’re running. (Sometimes you make new classes, methods, or variables while you’re running, but they usually follow some pre-set plan, so there’s still a lot of “not moving” involved.)

When I’m writing software, I usually build the Structure first, then I work on the Actions, and then I work on the displaying of the Result. Some people work backwards from the Results, that’s fine too. Probably the only inadvisable thing to do is to start with the Actions, since it’s kind of confusing to be performing Actions without a Structure and with no defined Result.

There’s so much to this concept that I could probably write a whole book just on this one topic, but I think this is a decent introduction, and I’m sure that given this, you can think of lots of other useful applications of it.

-Max

Comments: 0

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

When we think about software security, the first question that we ask is, “How many different ways could this program possibly be attacked?” That is, how many “ways in” are there? It’s a bit like asking “How many doors and windows are there on this building?” If your building has 1 exterior door, it’s very easy to protect that door. If it has 1000, it will be impossible to keep the building secure, no matter how good the doors are or how many security guards you have.

So we need to limit the “ways in” to our software to some reasonable number, or it won’t ever be secure. That’s accomplished by making the overall system relatively simple, or breaking it down into very simple and totally separate component parts.

Then, once we’ve limited the ways in, we need to start thinking about “How many different possible attacks are there against each way in?” We limit that by making the ways in themselves very simple. Like a door with only one unique key, instead of a door that can take five different keys, all of which individually will open the door.

Once that’s done, we limit how much damage any attack could do if it got through. For example, in a building, we’d make any given door only allow access to one room.

All of this explains, for example, why Windows is fundamentally flawed and will never be secure, and why UNIX-based systems have a better reputation for security.

Standard UNIX has a very small number of system calls that are used to implement the vast majority of all UNIX programs out there. (Even the extended list is only about 140 system calls, though most of those are never used by the average program.) Each system call is extremely specific and does one very limited thing.

Windows, on the other hand, has a ridiculous set of system calls that are confusing, take too many arguments, and do too much.

Going up to a higher level in the system, the Windows API is massive and complex. It’s a strange beast that controls both the OS and the GUI. There’s really no equivalent thing in UNIX (because the OS and the GUI are separate), but we can at least compare parts of it. Here’s The Windows Logging API. Here’s the Linux Logging API. There’s just no comparison. It’s like a joke. There’s so many “ways in” to any part of Windows that it will never be fundamentally secure.

You might say, “Well, I haven’t had a virus on my Windows machine in a long time.” That’s not what I’m talking about–I’m talking about fundamental security. In order to have a secure Windows machine, you have to have a firewall that asks you every time a program wants to make an outbound connection. You have to have a spyware scanner. You have to have antivirus software that slows down your computer by as much as 2000%. If Windows was secure, you wouldn’t need those things.

When we design our own systems, keeping them simple is the only real guarantee of security. We keep each “way in” to the system as simple as possible, and we never add more “ways in” than we absolutely need. These are compatible things, too, because the simpler each “way in” is, the fewer we’ll actually need. That may not make sense until you think about it this way: If all actions on the system can be reduced to, say, 13 fundamental function calls, then the user can do everything with those 13 calls, even if they’re not very powerful individually. If instead we only let them do 100 different specific tasks, and don’t allow them to use the 13 fundamental calls, we have to add a new function for every specific task.

There are lots of other “ways in” to a program than just its public API, too. How the user interface interacts with the backend–that involves various “ways in”. Can we access this program’s internal structure from another program? That would be another “way in.” There’s lots of ways to apply this principle.

Any way you slice it, though, the best way to get real security in things is simplicity. We shouldn’t have to put a small army in front of our software just to keep it secure. It should just fundamentally have so few “ways in” that it doesn’t need the protection, and those “ways in” should be so streamlined and simple that they’re impossible to exploit.

-Max

Comments: 14

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

But what is it that makes all that stuff a computer? Why do we look at it and go, “Oh yeah, that’s a computer,” as opposed to, say, “Oh, that’s just a TV,” or “That’s where I keep the leprechauns at night.”?

Some people try to define the word “computer” just by saying “it’s got such and such parts and they all work this way,” but that’s like saying “airplanes have two wings and jet engines.” It’s true, but I could build an airplane that didn’t have two wings or jet engines. The way something works is not a definition for that thing.

Others try to define it mathematically, but that can also be somewhat limiting, because then only the devices that fit into your mathematical scheme are computers, and there are multiple mathematical models that would all be considered “computers.”

So I turned to the dictionary. That was fun for me–I’m a dictionary fanatic. I’ve got lots of great dictionaries, and there are even more online. The Compact Oxford English Dictionary had the best definition, as it turned out.. I was very happy with it at first, but when I started to think about it, it didn’t quite work. For example, it calls computers “an electronic device,” and we know that computers can be built without electronics.

So I worked to come up with a definition of my own. Strangely enough, the key question that it boiled down to was “Why is a player piano not a computer?” It “processes information” by playing notes from its roll. If you gave it an etching machine, it could “store information” back on to the roll. But despite all that, it’s clearly not a computer. What is a computer doing that is fundamentally different from a player piano, that a player piano could never do?

After about two years, I finally came up with an answer that was both simple and all-encompassing. A computer is:

Any piece of matter which can carry out symbolic instructions and compare data in assistance of a human goal.

And that, my friends, is really it. My only thought left is whether I should say “a series of symbolic instructions” to more clearly differentiate it from a calculator. What do you think?

-Max

Comments: 35

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

Imagine that you are building a structure out of lead bars. The final structure will look like this:

   |
_|_|_|_
   |
   |
   |

You have to build the structure and put it up at a certain location, so that people can use it (for this example, we don’t care what they need it for, but assume that they need it for some specific reason).

The lead bars represent the individual pieces of your software. Putting it up at the location is like putting your software into production (or sending it out to your users). Everything else should be fairly clear as to how it translates to software, if you think about it. You don’t have to translate everything to software in your mind as you read, though. Everything should be quite clear if you just imagine that you really are just building a structure out of lead bars.

The Wrong Way

Imagine that you were building this all by yourself, and that you had to make the bars out of raw metal. Here’s the wrong way to build it:

1. Make one tall lead bar, and lay it flat on the ground in your workshop:

   |
   |
   |
   |
   |

2. Cut a hole through the tall bar, and measure that hole.
3. Make a new bar that will fit through that hole:

   _____

4. Put that new bar through the hole and weld them together permanently:

     |
   __|__
     |
     |
     |

5. Cut two holes in the horizontal bar, measure them, and make two new lead bars that will fit in those individual holes:

   |   |

6. Insert the two bars into the horizontal bar, and weld them together permanently:

      |
   _|_|_|_
      |
      |
      |

7. With a forklift, put this into a truck to move it to the location where it’s supposed to be (It’s too heavy to move by yourself.)
8. With a pulley, make the construction stand upright and put it into the ground.
9. Discover that it won’t stay up by itself, but if you put some blocks next to it as an emergency solution, it doesn’t fall over:

      |
   _|_|_|_
      |
     _|_
    | | |

10. Three days later, watch the structure fall over and break because the blocks aren’t actually a permanent solution.
11. Unfortunately, part of the horizontal bar has snapped, and you have to fix it. This is difficult because the bars are all welded together, so you can’t easily take out the bar and replace it with another one. You either have to build a whole new structure or weld together the broken bar. Welding the broken halves together creates a weak bond, but it’s cheaper than building a whole new structure, so you just weld them.
12. Put stronger blocks next to the structure to keep it up.
13. Next week, the weather breaks the welded bars. Weld them back together again.
14. In six days, watch the structure fall over because blocks are not a permanent solution.
15. Repeat the last few steps until you run out of money or time.

Analysis of The Wrong Way

So, what was good about the above process? Well, it did allow one person to successfully complete a structure. In software terms, that one person “made something that works.” It also created a lot of work for one person, which is good if that one person wanted a lot of work.

What was bad about it?

• The bars all had to be made in sequence, individually.
• Problems with the final structure (that it wouldn’t stay up) were only discovered after it was entirely built and in place.
• When problems were discovered, they were just “quick fixed” without planning for the future.
• It took enormous effort to move the completed structure into place.
• If we ever had to change the configuration of the bars, we couldn’t, because they’re welded together. We’d have to build a whole new structure.
• The completed structure requires frequent attention.

And I’m sure we could come up with other faults. This whole analogy (including the parts below) could be analyzed all day.

Bringing It To a Group

The biggest problem with the Wrong Way process is that it wouldn’t work at all if there were multiple people working on the project (as there usually are in real-world software projects). The main problem is that you had to measure all the holes before you built a bar, so everything had to be done by one person, in order.

There are, generally, two ways to solve this problem:

1. Write a specification for the sizes of all the individual holes beforehand, and then spread out the work of making all the different bars for each hole.

   This is problematic because one person has to write this specification, and if this were a large project (imagine thousands of holes instead of just three or four), it would take a lot of time. Nobody else on the team can be working until the specification is completed. The spec could be full of mistakes–there are as many chances for mistakes as there are holes specified, so if there are thousands of holes, that’s a lot of chances for errors to be made.

2. Just say, “All bar holes will always be the same size and in the same places on the bars. Bars can be screwed together.” Then set everybody to making bars with standardized holes (or go buy them from the store).

   That is simple, and it gets everybody working at once. Because you’ve standardized your bars, you’ve lost a little flexibility in dealing with any special cases that come up (maybe a half-width hole would be more useful in some part of the structure). However, you should be able to build a decent structure entirely with standard holes, so that’s not too much of a problem. And when you have a standard, you can make specific exceptions in some places more easily than if things are not standardized.

   Of course, with this method it is very important that you do a little research to pick a good hole size and good bars.

The Right Way

So, what would our process look like for many people all using standardized bars that screw together? (This is the right way to build something.)

1. Have your team all go build (or buy) their individual bars. You can have as many people working simultaneously as there are bars in the structure.
2. Have them test their individual bars to make sure that they won’t break.
3. Have them carry their individual bars to the place where the structure needs to be.
4. Put the first bar into the ground, standing upright:

   |

5. Push on the first bar from all angles to see if it is going to fall over.
6. Screw in a second bar to the first one:

   |
   |

7. Test the complete structure now, only to find that it’s not strong enough to stand by itself.
8. Attach unbreakable steel ropes to the sides of the structure, like so:

     /|\
    / | \

   These ropes should be able to withstand anything within reason, or even well beyond reason.

9. Test it again and find out that it now can stay up no matter how hard you push on it.
10. Add a third bar, and put new ropes on so that it looks like this:

       /|\
      //|\\
     // | \\

11. Remove the lower ropes:

       /|\
      / | \
     /  |  \

    (Anybody who’s been involved in refactoring Bugzilla can remember doing a lot of things that sound just like these last two steps. )

12. Test it again.
13. Continue these steps until you have a completed structure:

          |
       _|_|_|_
      /   |   \
     /    |    \
    /     |     \

14. When a pipe breaks in three months, figure out what was wrong with that pipe, fix the problem, and replace it with a new pipe that fits into the same holes. The structure is just as strong as it was before.
15. Continue the above process until you no longer have to pay attention to the structure and it just stays up all by itself.
16. Adjust the structure as necessary for the changing requirements of the users of the structure, which is easy because the holes are all standardized.

So, did you notice that we followed all the Laws Of Software Design?

• We thought about the future. We did that for the entire process, but we particularly did it when we put on unbreakable steel ropes that would last no matter what happened in the future.

  Also note that we didn’t try to predict the future, we just followed our principles so that no matter what happened, our structure was going to stay together and be easy to build.

• We allowed for change by screwing the bars together instead of welding them. We also put standardized holes in all the bars, even if we didn’t need them, in case we needed to add more bars in the future.
• In every step of creating the structure, we kept our changes small and tested everything as we went. Creating each individual bar was a small task, and we put them together in small steps.
• And of course, the most important decision we made was to keep it simple by making all the holes consistent and standard, and keeping each piece small and simple.

Whether you are one person or a thousand, whether your project is 10 lines of code or 10 million, this process will work.

-Max

Comments: 2

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

Bugs most commonly come from somebody’s failure to reduce complexity. Less commonly, they come from the programmer’s misunderstanding of something that was actually simple.

Other than typos, I’m pretty sure that those two things are the source of all bugs, though I haven’t yet done extensive research to prove it.

When something is complex, it’s far too easy to misuse it. If there’s a black box with millions of unlabeled buttons on it, and 16 of them blow up the world, somebody’s going to blow up the world. Similarly, in programming, if you can’t easily understand the documentation of a language, or the actual language itself, you’re going to mis-use it somehow.

There’s no right way to use a box with millions of unlabeled buttons, really. You could never figure it out, and even if you wanted to read the 1000-page manual, you probably couldn’t remember the whole thing well enough to use the box correctly. Similarly, if you make anything complex enough, people are more likely to use it wrongly than to use it correctly. If you have 50, 100, or 1000 of these complex parts all put together, they’ll never work right, no matter how brilliant an engineer puts them together.

So do you start to see here where bugs come from? Every time you added some complexity, somebody (and “somebody” could even be you, yourself) was more likely to mis-use your complex code. Every time it wasn’t crystal clear exactly what should be done and how your code should be used, somebody could have made a mistake. Then you put your code together with some other code, and there was another chance for mistakes or mis-use. Then we put more pieces together, etc.

Often, this sort of situation happens: the hardware designer made the hardware really complicated. So it had to have a complicated assembly language. This made the programming language and the compiler really complicated. By the time you got on the scene, you had no hope of writing bug-free code without ingenious testing and design. And if your design was less than perfect, well…suddenly you have lots of bugs.

This is also a matter of understanding the viewpoint of other programmers. After all, something might be simple to you, but it might be complex to somebody who isn’t you.

If you want to understand the viewpoint of somebody who doesn’t know anything about your code, find the documentation of a library that you’ve never used, and read it.

Also, find some code you’ve never read, and read it. Try to understand not just the individual lines, but what the whole program is doing and how you would modify it if you had to. That’s the same experience people are having reading your code. You might notice that the complexity doesn’t have to get very high before it becomes frustrating to read other people’s code.

Now, once in a while, something is really simple, and the programmer just misunderstood it. That’s another thing to watch for. If you catch a programmer explaining something to you in a way that makes no sense, perhaps that programmer misunderstood something somewhere along the line. Of course, if the thing he was studying was extremely complex, he had basically no hope of fully understanding it without a PhD in that thing.

So these two things are very closely related. When you write code, it’s partially your responsibility that the programmer who reads your code in the future understands it, and understands it easily. Now, he could have some critical misunderstanding—maybe he never understood what “if” meant. That’s not your responsibility. Your responsibility is writing clear code, with the expectation that the future programmer reading your code understands the basics of programming and the language you’re using.

So, there are a few interesting rules that you can get out of this one:

The simpler your code is, the fewer bugs you will have.

Always work to simplify everything about your program.

-Max

Comments: 9

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

But really, when we say “bug” what exactly do we mean?

Here’s the precise definition of what constitutes a bug. Either:

1. The program did not behave according to the programmer’s intentions.
   or
   
2. The programmer’s intentions did not fulfill common and reasonable user expectations.

So usually, as long as the program is doing what the programmer intended it to do, it’s working correctly. Sometimes what the programmer intended it to do is totally surprising to a user and causes him some problem, so that’s a bug.

Anything else is a new feature. That is, if the program does exactly what was intended in exactly the expected fashion, but it doesn’t do enough, that means it needs a new “feature.” That’s the difference between the definition of “feature” and “bug.”

Note that hardware can have bugs too. The programmer’s intention is rarely “the computer now explodes.” So if the programmer writes a program and the computer explodes, that’s probably a bug in the hardware. There can be other, less dramatic bugs in the hardware, too.

Essentially, anything that causes the programmer’s intentions to not be fully carried out can be considered a bug, unless the programmer is trying to make the computer do something it wasn’t designed to do. For example, if the programmer tells the computer “take over the world” and it wasn’t designed to be able to take over the world, then the computer would need a new “take over the world” feature. That wouldn’t be a bug.

With hardware, you also have to think about the hardware designer’s intentions, and common and reasonable programmer expectations. At that level, software programmers are actually the main “users”, and hardware designers are the people whose intentions we care about. (Of course, we also care about the normal user’s expectations, especially for hardware that users interact with directly like printers, monitors, keyboards, etc.)

-Max

Comments: 4

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

There are some things about the future that you do not know.

Obviously it’d be ideal if we were all-knowing and could perfectly predict every consequence of every decision we’ll ever make. But that’s impossible. In fact, it’s so far from possible that if you predict more than half of the consequences of your engineering decisions, you’re godlike or just really lucky.

Let’s take an example outside of the realm of programming: CDs, which were designed in 1979 to replace cassette tapes as the primary method of listening to music. Who could have predicted that 20 years later, DVDs would be made the same size and shape so that manufacturers could make CD/DVD drives for computers? Did anybody imagine the problems of spinning a CD fifty times faster than it was supposed to be spun, for reading in a CD-ROM drive?

This is why, in engineering, we have “guiding principles.” There are certain rules that, when we follow them, keep things working well no matter what happens in the future.

In the case of software, I’ve summed up the most basic guiding principles as the Laws Of Software. The very first (and most important) law is that the future is more important than the present (because it’s very big and the present is very small). But here’s the thing to know about that: that doesn’t mean you have to predict everything about the future. Instead, it explains why you should be making decisions according to the laws of software–because those laws make for good future software, no matter what that future is.

Sometimes it can be hard to understand why you should be stupid, dumb simple, if you’re only thinking about the present. And it can be impossible to predict exactly why or how simplicity will help you in the future. I can tell you that it will help, and you’ll be glad you did it, and if you don’t believe me (which you are welcome to do–your mind is yours!) you’re going to end up in mess of trouble somewhere down the line, in a future you can’t predict.

I’m not singling you out, here. You’re not dumb. It’s just that nobody can predict the total future of a piece of software, except to know that certain decisions now will make that future better, and that other decisions will make that future worse. We know this from decades of experience in the software development industry–certain basic principles invariably lead us in the right direction, and certain “anti-patterns“, if followed consistently, invariably lead us into trouble.

To be a successful software developer, you have to be willing to not know some things about the future, and trust that following your principles is the right thing to do. Sometimes it can take years to see that you were right, but it’s a glorious day when you finally realize that your product still exists because you made the right decision three years ago, when you couldn’t even prove to anybody that it was the right decision, but forged ahead anyway with your “excessive simplicity” because you knew it was the right thing to do.

-Max

Comments: 5

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

For example, it’s very difficult to make a car move if it has square wheels. You’re going to be spending lots and lots of time figuring out how to make the car work, when really it should just have round wheels.

Any time there’s an “unsolvable complexity” in your program, it’s because there’s something fundamentally wrong with it. If the problem is “unsolvable” at one level, maybe you should back up and look at what’s underlying the problem. Maybe you put square wheels on the car, and now you’re trying to figure out how to make it go fast.

Programmers actually do this quite often. For example, “I have this terribly messy code, now it’s really complex to add a new feature!” Well, your fundamental problem there is the that code is messy. Clean it up, make the already-existing code simple, and suddenly adding the new feature will be simple.

What Problem Are You Trying To Solve?

If somebody comes up to you and says something like, “How do I make this pony fly to the moon?”, the question you need to ask is, “What problem are you trying to solve?” You’ll find out that they really need to collect gray rocks. Why they thought they had to fly to the moon, and use a pony to do it, only they know. People do get confused like this.

So when things get complex, back up and you look at the problem that you’re trying to solve. Take a really big step back. You are allowed to question everything. Maybe you thought that adding 2 and 2 was the only way to get 4, and you didn’t think about adding 1 and 3 instead, or just skipping the addition entirely and just putting “4” there. The “problem” is “How do I get 4?” Any method of solving that problem is acceptable, so figure out what the best method would be, for the situation that you’re in.

Discard your assumptions. Really look at the problem that you’re trying to solve, and think about the simplest way to solve that problem. Not “How do I solve this problem using my current code?” Not “How did Professor Bob solve this problem in his program?” No, just how, in general, in a perfect world, should that problem be solved? From there, you might see how your code needs to be re-worked. Then you can re-work your code. Then you can solve the problem.

-Max

Comments: 18

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

Never “fix” anything unless it’s a problem, and you have evidence showing that the problem really exists.

Of course, most of us know this as “If it ain’t broken, don’t fix it.” However, these wise words are frequently ignored, because many developers don’t have a good understanding of what “broken” means. Often, developers just imagine that users have a problem with something, and start fixing it. Or they go off and develop features that don’t solve anybody’s problem. This is far, far more common than you might think.

So that’s why I say you should have evidence that there’s a problem. Without that evidence, you could just be fixing things that aren’t actually problems, and if you go around fixing things that aren’t broken, you’re going to break things. And not only could you be generating bugs, but you’re wasting your time and adding complexity to your program for no reason. You need evidence that there’s a problem, before you start coming up with a solution.

What do I mean by “evidence”? Well, five users report that when they push the red button, your program explodes. Okay, that’s good enough for me! Or you push the red button, and you notice that the program explodes.

However, just because a user reports something doesn’t mean it’s a problem. Sometimes a user just didn’t realize that your program had some feature already, and so asked you to implement something else silly. For example, you write a program that sorts a list of words alphabetically, and a user asks you to add a feature that sorts a list of letters alphabetically. Your program already does that. (Actually, it already does more than that. This is often the case, with this sort of confused request.) So in this case, the user thought there was a problem, but there wasn’t even really a problem, even though he could maybe present “evidence” that he couldn’t sort a list of letters. (He just didn’t realize that he should use the word-sorting feature.)

Note that if you get a lot of requests like the above, it probably means that users can’t easily figure out how to find what they need. There’s some complexity that needs to be reduced on your end.

Finally, sometimes a user will report that there’s a bug, but actually that’s the program behaving exactly as you intended it to. In this case, it’s a matter of “majority rules.” If a significant number of users think that the behavior is a bug, it’s a bug. If only a tiny minority (like one or two) think it’s a bug, it’s not a bug.

The most famous error in this area is what we call “premature optimization”. That is, some developers seem to like to “make things go fast”. But they do it before they know that it’s slow! This is like a charity sending food to rich people. “We just wanted to help people!” Right—illogical, isn’t it? They’re solving a problem that doesn’t exist.

The only parts of your program where you should be concerned about speed are the exact parts that you can show cause a real performance problem for the users. The rest of the code, the primary concern is simplicity, not “make things go fast”.

There are infinite ways of violating this rule, but the way to follow it is so simple: just get real evidence that the problem is valid before you fix it.

-Max

Comments: 0

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

Well, like I said in the my design philosophy it helps to keep your changes small. But if you want to avoid even more defects, and eliminate them even from your small changes, there’s another law that can help you. And it doesn’t just reduce defects–it keeps things maintainable, makes it easy to add new features, improves the overall understandability of your code, and knowing it helps you make better software, all around. This Fourth Law of Software Design is:

The maintainability of a system is inversely proportional to the complexity of its individual pieces.

Where “maintainability” means “ease of maintenance.” Extreme unmaintainability would be the total inability to maintain some part or the whole of a piece of software. Perfect maintainability is impossible, but it’s the goal you strive for–total change or infinite new code with no difficulty.

This law is largely empirical, meaning that I figured it out by observation, not by logic. However, it does have a logical basis:

1. The simpler something is, the easier it is to understand. For example, a beach ball is very simple–a single large round object that you throw around–and is something that anybody can understand.
2. The more complex something is, the harder it is to understand. For example, a jet plane is very complex, and takes extensive training to use and understand. Complexity is not the only factor that makes things hard to understand, but with enough complexity, anything can become hard to understand.
3. The less you understand something, the harder it is to fix or modify it.
4. Thus: The more complex something becomes, the harder it is to modify (maintain) it.

However, you’ll notice that I didn’t say anything about the complexity of the whole system, in the law. I only mentioned its individual pieces. Why did I do that?

Well, an average-sized computer program is so complex that no human being could comprehend it all at once in their mind. It’s only possible to comprehend pieces of it. So we actually always have some large, complex structure for our whole program. What then becomes important is that the pieces can be understood when we look at them, and that we understand how the pieces relate to each other. The easier it is to understand the pieces, the more likely it is that any given person will understand them. That’s particularly important when you’re handing your code off to other people, or when you go away from your code for a few months and then have to come back and “re-learn” what you did, by reading your own code.

Let’s make an analogy, to demonstrate the principle. Imagine that you’re building a 30-foot tall steel structure. There are two ways to make it–you could make it out of a bunch of small girders, or you could try to forge three huge pieces of steel and put them together. With the girders approach, it’s easy to make or buy the individual pieces. The three huge pieces, on the other hand, have to be carefully custom-made and worked on extensively. With the girders, if one breaks you just replace it with an identical spare part. With the “huge pieces” approach, when one breaks you have to evacuate the structure, remove 1/3 of it, create a whole new custom piece, and then add that back in without collapsing the whole structure. The girders are simple, the huge pieces are complex.

So why do people sometimes write software with the “huge pieces” approach instead of the girders approach? It’s because there’s a perceived savings of time when you’re first creating the software, with the “huge pieces” method. With a bunch of small pieces, there is a lot of time spent putting them together. You don’t see that with the huge pieces–there’s three of them, they snap together, and that’s it. But the part that’s missed here is that it took way more time to create the three huge pieces than it did to create the girders. When you’re making a huge, complex single piece, any tiny error means that the whole thing has to be fixed or re-worked. And per observation in the practical world of programming, you will spend far more time fixing and re-working those huge pieces than you will putting together the small girders. So even though the time spent creating the “huge pieces” might seem like “productive, important time” and the time spent putting together the girders might seem like “busywork” or “wasted time,” the “girders” approach is actually more efficient.

I could go on and on about this, but you can find out about it for yourself. If you don’t believe me, spend a few years working on a software project where all the parts are very complex. I don’t recommend that you do that, but if you need any proof of this law for yourself, that would be a good (if painful) way to get it. Of course, you could also just apply the law and see if your software keeps on being maintainable–that’s a much less painful demonstration.

So how do we use this law, in the practical world of programming? Well, generally I recommend that people make the individual components of their code as simple as possible. Ideally this would start way down at the assembly language level, but you don’t always get simplicity there. Nor do you always get a simple programming language. But with what you have, strive for simplicity. Make everything as simple as possible. Don’t be afraid to be stupid, dumb simple. There is no limit to how simple you can make something, because if you go too far, your “simplicity” will start becoming complex. (In other words, you’ll be overengineering.) So just be as simple as you can possibly be, and if you overdo it (which almost never happens), it’ll be pretty obvious.

-Max

Comments: 8

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

Our next law is, once again, axiomatic, and needs no derivation:

It is impossible to introduce new defects in your software if you do not change anything about it.

This is important–and categorized as a law–because defects violate our purpose of helping people. If something is a defect, by definition it is not helpful to people, and we need to avoid it.

This is also sometimes stated more informally as “You can’t introduce new bugs if you don’t add or modify code.” I’m not sure that “code” entirely covers “anything about it,” so I didn’t state it that way.

Of course, the reverse would be:

It is possible to introduce defects into your software if you change something about it.

Which leads to:

The more changes you make, the more likely you are to introduce a defect.

The funny thing is that this seems to be in conflict with the second law, and in fact it is. It’s the balancing act between the second and third law that requires your intelligence as a software designer.

Combining all three laws, we get:

The best design is the one that allows for the most change in the environment with the least change in the software.

And that, pretty simply, sums up my design philosophy.

However, it’s important to limit that somewhat. Although that may be the best code design, that rule doesn’t necessarily lead to the best user-facing design. An equivalent law for users would be something like, “If you never use the program it won’t break,” but I’m not sure that’s so useful. This third law is about preventing bugs, not about making things work nicely. You still want things to work nicely and do what people want–I’m just telling you here how to avoid bugs.

Another thing to know here is that, given our first two laws, it’s an error to write a system that “does everything we could ever possibly need,” but not make it flexible enough to cope with future change. That might seem like a good way to “avoid future changes in the software”, but really you’re just bringing all that change into the present, introducing the same number of bugs, and then not allowing any room to grow. And no program will do everything you could ever possibly need–there will always be future requirements that you cannot predict. This is covered more in Designing Too Far Into The Future.

On the other hand, you can overengineer to the point where your design is so flexible that creating and maintaining it is extremely difficult. That would be the point where you reach a level of flexibility that is not necessary to the real future (thinking about this in relation to the First Law).

However, overengineering is a much less common error than designing too far into the future. When in doubt, expect change, and plan your code in ways that will make change as simple and small as possible.

-Max

Comments: 7

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

This law is derived from things that we know about the physical universe. From physics we know:

Nothing stays still.

That is, there is no matter or energy anywhere that isn’t moving. Even the atoms in your desk are vibrating furiously, back and forth. It is actually impossible to make them stand still.

So, from that we can then assume:

Anything that exists in the physical universe will change.

Now, that might not be so obvious in some respects. After all, couldn’t you just have something vibrate back and forth forever in one space? Well, let’s ignore that that vibration is “change”, because it’s not really the kind of change I’m talking about. You have to look at it this way: as soon as a vibrating object strikes another vibrating object, one of the vibrations will change. With enough objects in the universe, change then becomes unavoidable. There are enough objects in this universe (particularly the world we live in every day) that change is thus extremely common and likely. Also, people change things, above and beyond these physical laws.

So, you can guarantee this:

The world around your program is going to change.

It could be that you wrote a program for four-wheeled cars and now everybody drives 18-wheel trucks. It could be that you wrote a program for 10 year olds and then 10-year-old education got so bad that they couldn’t use it anymore. Really, it could be anything–the only thing you can guarantee is that something is going to change.

This leads us to our second law of software design:

Your software is going to change.

It’s not going to change by itself, but unless you just give up and decide you don’t want people to use your software anymore, you as a programmer are going to have to accommodate the demands of a changing environment. And that changing environment includes you and your users, too. One day you could wake up and decide that you don’t like how “feature A” works and re-write that piece of the program. Or you might suddenly get new users who don’t like how “feature B” works and have to change that. Really, the possible causes of change are limitless–the only thing you can guarantee is that something will change.

That leads us nicely into the next statement we can derive here, looking at our second law in the context of our first law:

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

That is, as you go into the infinite future, you start tending toward a 100% possibility of every single piece of your program changing. In the next five minutes, no part of your program will probably change. In the next 10 days, a small piece of it might. In the next 20 years, I’m betting that a majority of it (if not all of it) will change.

This is our primary concern in designing for the future–that we allow for and expect change, not that we design ourselves rigid structures that will “stand forever” but suddenly become useless when the environment around them changes.

When you design for the future, you are designing for change.

-Max

Comments: 10

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

From the purpose of software, we know that when we write software, we’re trying to help people. So, one of the goals of a science of software design should be:

To allow us to write software that is as helpful as possible.

Secondly, we usually want people to keep on being helped by our software. So our second goal is:

To allow our software to continue to be as helpful as possible.

Now, that’s a great goal, but any software system of any size is extremely complex, so allowing it to continue being helpful is quite a task. Maintaining it over time can be quite a bit of work. Even just creating the system in the first place can be nightmarish if you don’t have some guidelines to follow, or haven’t already had experience doing it. So that leads us to our third goal:

To design systems that can be created and maintained as easily as possible by their programmers, so that they can be–and continue to be–as helpful as possible.

When software is easy to create, a programmer can spend more time focusing on being helpful to the user, and less time focusing on the details of programming. Similarly, the easier it is to maintain a piece of software, the easier it is for a programmer to have that software continue to be helpful.

This third goal is probably the one traditionally thought of as the goal of software design, even if it’s never stated explicitly. However, it’s very important to also have the first and second goal to guide us.

The phrase “as easily as possible” in the third goal is very important. The idea is to make things easy to create and maintain, not to make them difficult or complex. That doesn’t mean that everything will be immediately easy–sometimes it takes time to learn a new technology or design something well. But in the long run, your choices should lead to easier maintenance and creation for your software.

Sometimes the first goal (being helpful) and the third goal (easy maintenance) are a little bit in conflict–sometimes making your software helpful can make it harder to maintain. However, I believe that these two goals have been much more in conflict, historically, than they need to be. It is absolutely possible to create a totally maintainable system that is yet extremely helpful to its users. And in fact, if you don’t make it maintainable, it’s going to be quite difficult to meet our second goal of continuing to be helpful.

All this, of course, leads us quite nicely back into our Primary Law, which is where we’d be going next if this were a book. The only thing I’d add to the Primary Law article is that under most circumstances, there’s a lot more potential help to be done in the future than there is in the present. (If there’s no potential help to be done in the future for your software, then it doesn’t have much of a life expectancy anyway, so we don’t worry too much about that situation.) In other words (and as I’ll be talking about more, later), by focusing on the second goal (continuing to be helpful), it is often possible to achieve the first (being helpful). That doesn’t mean first goal is unimportant–I’m just giving you something to think about.

-Max

Comments: 0

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

Similarly, when we write software, we should have some idea of why we’re doing it, and what the end goal is.

Now, is there some way that you could sum up what the purpose of all software is? If there was such a statement possible, it would give orientation to our whole science of software design, because we’d know what we were going for.

Well, I think I’ve managed to derive a single purpose that would fit all software:

To help people.

For example, Bugzilla exists “to help people track bugs.” Firefox exists “to help people browse the web.” Remember, you could browse the web entirely by reading HTML yourself–but Firefox (or your web browser of choice) sure does help.

Even if you wrote a piece of software to help animals or plants, it would still be “to help people help animals or plants.”

Software is never there “to help inanimate matter.” Software does not exist “to help the computer.” It always exists to help people. Even when you’re writing libraries, you’re writing “to help programmers”, who are people. You are never writing “to help the computer.”

Now, what does “help” mean? Well, that is somewhat a subjective thing, and somewhat not. Look it up in the dictionary. There are many things you could help with–organizing a schedule, writing a book, planning a diet, anything. What you help with is up to you, but the purpose is always to help.

People who cannot conceive of helping another person will write bad software–their software won’t help people. In fact, I might theorize (as a guess based on some personal observations) that your potential ability to write good software is limited only by your ability to conceive of helping another.

The purpose of software is not “to make money” or “to show off how intelligent I am.” Anybody writing with those as their only purposes is violating the purpose of software and is quite likely to get into trouble. Granted, both of those are a way of “helping” yourself, but that’s a pretty limited scope of help and, I would argue, is likely to lead to lower-quality software than software genuinely designed to help individuals do what they need or want to do.

So anyhow, there you have it. When we are making decisions about software, our guiding principle can be how we can help. It’s possible to help more or less, to help fewer or more people or things. With that as a yardstick, it’s possible to understand our Laws Of Software Design and how we should be making decisions about software.

-Max

Comments: 12

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

For the sake of this definition, let’s say that the process of making software is composed of three parts: administrative decision-making, technical decision-making, and actual coding. Of course, there’s also testing, releasing–there’s lots of parts to software in the real world. I’m just making an artificial division here to help define one part of the three I mentioned.

By “administrative decision-making” I mean the sorts of decisions that would be made primarily by managers in a software organization. These are scheduling, cost estimates, what programmer to assign to what task, etc. There are a lot of theories and study in this area–I think that it’s actually fairly well-covered (even if not completely made scientific yet) by lots of people. That is not the area I’m talking about when I say “software design.”

The other side of those three parts is “coding”. That’s where you sit down and actually write the program, typing strange words onto a screen in the hope that the computer will do something. This process is partially covered by the study of computer science, which gives us mathematical ways of modeling code and information. It’s also covered by the manual of whatever language we’re writing in. Coding is what you do after you’ve already made decisions–it’s just the actual process of telling the computer what to do, or figuring out how to make the computer perform the actions you want.

The last piece, in the middle, is what I’m loosely calling “technical decision-making.” Often, the process of technical decision-making and coding happen so fast that they are mentally indistinguishable, particularly if you are an experienced programmer. You just “know” what to do and type it in. However, the decision-making and the coding are actually separate processes. Technical decisions would be things like: “Do we go with a functional programming language or a procedural programming language?”, “Should we have unit tests?”, “How should we style our code?”, “Should we optimize for speed?”, and even-less-high-level decisions, until you get down to the actual coding. Basically, anything that happens in your mind, on a piece of paper, on the whiteboard, etc. before you start programming, that’s software design as I mean it. Anything that involves the overall design of the system or the technical decisions you make while creating the system would fall under this category.

It could just as easily be called “software creation”, but I think that would get too confused with coding and computer science. Similarly, I started out calling it the subject of “software”, but that has the same problems. “Software architecture” is too limiting, as it’s often thought of in terms of classes and objects, and might not include things like unit tests, code style, or other technical decisions you have to make in the process of creating software.

I suspect that in time I will come up with an even-more-precise definition, but this should at least give you some idea of what I mean, for now.

What I think we primarily lack in the field of software design is a series of fundamental truths on which we can base our technical decisions. Experienced software developers “know” what “the right thing to do” is, but why is that the right thing? What makes that “right?” Many Perl developers, for example, would claim that Perl is “the right way”, in direct conflict with the way other languages work. There are definite warring camps in this field–how can we figure out which way we should go?

Well, that’s one of my goals with this science (or subject) of software design–to help us be able to figure out where we should go in any given situation.

So, in my view, any science of software design would have to consist of:

1. An explanation of the purpose of software.
2. An explanation of the goals of the science.
3. A series of fundamental truths on which to base decisions.

And this would allow us to achieve:

1. The ability to make decisions that achieve the stated purpose of software.
2. Some way of understanding what causes errors (decisions that do not achieve the purpose) in software design.
3. A method (or methods) of preventing future errors.
4. A method (or methods) of fixing errors that already exist.

In my view, a science is only as useful as it can be applied. Physics is very useful because we can use it to build things, fix things, design new things, etc. I would like the science of software design to be directly applicable to the practical process of writing software, and the kinds of decisions that real programmers have to make every day. I can’t promise that the study will be perfect, but I can promise you that it will be useful.

-Max

Comments: 4

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

• Is universally true, without exception.
• Predicts phenomena that, when looked for, will be found to exist in the real world.

Some of the best laws are axiomatic, a big word meaning “obviously true.” For example, “Yesterday happened before today” is an axiomatic statement–the definition of the word “yesterday” makes that obviously true.

For the science of software design, we are lucky to have an axiomatic basic law which is senior to all others:

There is more future time than there is present time.

This is obviously true. “Now” is an infinitely small moment that quickly becomes another “now.” The future is infinite.

So, since the future is infinitely large and the present is infinitely small, we can derive another obvious statement:

The future is more important than the present.

Now, when we’re talking about an infinitely small present and an infinite future, what I’ve said there is pretty obvious. In the real world, though, we have to ask the question: how much future are we talking about? What’s more important, the next five minutes or the next ten years?

Well, in order to answer that question, we have to make one assumption: that you want your program to continue to exist and be used in the future. If you only want it to exist for the next five minutes, then those are the most important. If you want it to continue to be around for 10 years, then those 10 years are the most important.

So all together, this tells us how good our software design needs to be–it needs to be exactly as good as there is future time in which our software must exist.

If you’re writing a program that’s only going to be used once, you don’t have to worry about its design. If you’re writing a program that’s going to be used and modified by astronauts on a 100-year voyage to Alpha Centauri, you have to be really good.

So, this science of software design is a thing where you have choices–if you follow and understand all of its laws, you will have a program that survives very well into the future. If you follow none of them, your program won’t continue to exist very long, or at the very least, it will become more and more difficult to ensure its continued existence.

Now, keep in mind that sometimes in life, there are situations where what you do for the next five minutes determines whether or not you live or die. Similarly, in the real world of software, there can be situations where what your organization does right now determines whether you go bankrupt or not. These are totally valid decisions according to this law, because if your software falls entirely out of existence right now, then the next ten years don’t matter. There is no future existence for something that no longer exists. (Another axiomatic statement!)

However, such situations are generally the exception, not the rule. If you found yourself constantly in a situation where the next five minutes determined your life or death, wouldn’t you want to get out of that? Similarly, if you find yourself in an organization that always insists that the next five minutes are more important than the next ten years, perhaps you should consider leaving.

Now, don’t pass any of this off as unimportant just because it’s “obvious.” What matters isn’t the statement itself, but the importance placed upon the statement. This is the senior law of software design, from which all other aspects of good design flow without exception. If you know of any exceptions, I’d be happy to hear them so that I could refine the science using a higher primary law. But I’m not aware of any exceptions.

When thinking about this law, I usually apply it from the viewpoint of a programmer, not as a user. Sure, a program that is written now and can still be used in 20 years would be fantastically designed from a user’s perspective. But what I’m concerned about mostly is whether or not a software developer will be able to fix or modify this program 20 years from now. That’s an entirely realistic concern–there are programs that have been around for 20 years or more.

There are also other important things to think about in relation to this law–what you can and can’t know about the future. But that’s a subject for another blog.

-Max

Comments: 21

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.

These mathematicians are the people we would consider the modern founders of “computer science.” Computer Science is actually the mathematical study of information processing. It is not, as some people believe it to be, the study of computer programming. In fact, there is no science of computer programming. To understand how that could possibly be true, and what I mean, you have to know the history of programming.

The earliest computers were built under the supervision of computer scientists by highly skilled electronic engineers. They were run by highly-trained operators in tightly-controlled environments. They were all custom-built by the organizations that needed them (mostly governments, to aim missiles and crack codes), and there were only one or two copies of any given model.

Then, along comes UNIVAC and the whole notion of “commercial” computers. Now, there’s only so many advanced theoretical mathematicians in the world. If you start shipping out computers to everybody, you can’t ship a mathematician along with each one. So although some organizations, such as the United States Census Bureau, almost certainly had some highly-trained operators for their machinery, other organizations undoubtedly got their machine and said, “Okay, Bill from Accounting, this is yours! Read the manual and have at it!” And there went Bill, diving into this complex machine and doing his best to make it work.

Bill there is our first “working programmer.” He might have studied math in school, but he almost certainly didn’t study the sort of advanced theory needed to conceive and design the machine itself. But he can read the manual and understand it, and by trial and error, make the machine do what he wants.

Of course, the more commercial computers you ship, the more Bills you have and the fewer highly-trained operators you have. And if there’s one thing that Bill has, it’s job pressure. He has demands from management to “Get that task done now!” and “We don’t care how it’s done, just do it!” He figures out how to make the thing work according to its manual, and it works, even if it crashes every two hours.

Eventually Bill gets a whole team of programmers to work with him. He has to figure out how to design a system and split up the tasks between different people. Instead of being studied and mapped out like a standard science, the whole art of practical programming grows organically, more like college students teaching themselves to cook than like NASA engineers building a space shuttle.

So there’s this hodge-podge system for software development, and it’s all very complex and hard to manage, but everybody gets along somehow. Then along comes The Mythical Man Month, a book by a guy who actually looked at the process of software development and pointed out some things about it–most famously that adding more programmers to a project doesn’t necessarily make it faster. He didn’t come up with a whole science, but he did make some good observations about programming and managing software development.

Of course, then came a flurry of software development methods: the Rational Unified Process, the Capability Maturity Model, Agile Software Development, and others. None of these claim to be a science, just a way of managing the complexity of software development.

And that, basically, brings us up to where we are today: lots of “methods,” but no real science.

A science is composed of observations, experiments, and laws. Although we have hundreds of books of observations about practical programming, and “the world is our laboratory”, all of that has resulted in very few laws, which are the most important part of a science. That is, instead of coming up with methods to work around complexity, there ought to be some fundamental rules to follow that would lead to simplicity–ways to avoid complexity entirely and explain why what “works” in software development does work.

In reality, there are two missing sciences here. The first one is being worked on actively, and includes the various methods I mentioned above. That’s the science of managing software development. The fact that conflicting, equally-valid “opinions” seem to exist within the field indicates that the fundamental laws of software management have not been worked out. However, there is at least attention being given to the problem.

The other science, though, gets very little attention in the practical world of programming: the science of writing software. Very few people are taught that there is a science to writing software, in school. Instead, they are just shown “This is how it works in this programming language, now go write some software!”

The science I’m talking about is not Computer Science. That’s a mathematical study. I’m talking about a science for the “working programmer”–something that gives fundamental laws and rules to follow when writing a program in any language. One that’s as reliable as physics or chemistry in telling you how to create an application.

Some people might say that such a science is not possible, that software development is too variable to ever be described by simple, fundamental laws. Some people also once said that understanding the physical universe was impossible because “it is the creation of God and God is unknowable.” So unless you’re telling me computers are unknowable, I think that making such a science would be entirely possible.

Actually, I’ve started to collect some basic hypotheses for such a science, and I’m writing a book about it. I might post some of them here, but actually, all of what I’ve written in the blog so far actually comes from those hypotheses. That is, I haven’t really posted any of my hypothetical “laws” yet, but I have been posting data that I’ve derived from them.

Anyhow, I think that the primary source of complexity in software is actually the fact that this science is lacking. If programmers actually had a science for simplicity in software, there wouldn’t be nearly so much complexity, and we wouldn’t need crazy processes to manage that complexity.

Whenever there’s a problem with something, my instinct is to go philosophically above the level of the problem and look at it from there. If there’s some “unsolvable” effect happening to something, there must be some unknown cause on a higher level. So there you go–if the problem is complexity, then maybe it’s because there was no science of simplicity in the first place.

-Max

Comments: 11

Code Simplicity is brought to you by Max Kanat-Alexander and BugzillaSource.