Code Simplicity

Users Have Problems, Developers Have Solutions

In the world of software, it is the job of software developers to solve the problems of users. Users present a problem, and the developers solve it. Whenever these roles are reversed, trouble ensues. Continue reading


The Accuracy of Future Predictions

One thing we know about software design is that the future is important. However, we also know that the future is very hard to predict.

I think that I have come up with a way to explain exactly how hard it is to predict the future of software. The most basic version of this theory is:

The accuracy of future predictions decreases relative to the complexity of the system and the distance into the future you are trying to predict.

As your system becomes more and more complex, you can predict smaller and smaller pieces of the future with any accuracy. As it becomes simpler, you can predict further and further into the future with accuracy.

For example, it’s fairly easy to predict the behavior of a “Hello, World” program quite far into the future. It will, most likely, continue to print “Hello, World” when you run it. Remember that this is a sliding scale–sort of a probability of how much you can say about what the future holds. You could be 99% sure that it will still work the same way two days from now, but there is still that 1% chance that it won’t.

However, after a certain point, even the behavior of “Hello World” becomes unpredictable. For example, “Hello World” in Python 2.0 the year 2000:

print "Hello, World!"

But if you tried to run that in Python 3, it would be a syntax error. In Python 3 it’s:

print("Hello, World!")

You couldn’t have predicted that in the year 2000, and there isn’t even anything you could have done about it if you did predict it. With things like this, your only hope is keeping your system simple enough that you can update it easily to use the new syntax. Not “flexible,” not “generic,” but simply simple to understand and modify.

In reality, there’s a more expanded logical sequence to the rule above: Continue reading


Code Simplicity, Second Revision

In June, I released a second revision of Code Simplicity. Some of you probably already know, but I thought that I should let everybody else know, too.

The most important change is that book gets into the laws and rules of software design much more quickly now. It starts with a completely re-written Preface that tells the story of how I developed the principles in Code Simplicity, and why you might be interested in them. Then it gets into a much shorter Chapter 1 that distills everything from the old Chapter 1 into a few short pages, skips the old Chapter 2 (which was a long discussion about what it means for something to be a science) and goes right into the laws.

Particularly if you’ve read the original version, I’d really love to hear your feedback on how the starting content of the new revision feels to you!


P.S. If you bought the ebook from O’Reilly, you get every new revision for free, and there will probably be even more revisions than this one! If you got the ebook elsewhere, there’s a little link inside of the book itself that will let you “upgrade” to the O’Reilly editions for pretty cheap, so that you can get this revision and every other future revision for free, too. I’m not partial to any particular method of you getting the book, but the O’Reilly editions are definitely the best way to get the new revisions as they come out.


Software as Knowledge

I don’t often dive deep into the philosophical underpinnings of Code Simplicity, but I’ve been realizing more and more that there are a few philosophical principles behind the writings that would be valuable to share. Also, some of these philosophies haven’t been fully formed until I sat with the work for a long time, applied it in a lot of situations, and talked about it with many people. This one–a theory that I have developed over time about how software can be thought of and worked with in the mind–has sort of been percolating with me for quite a while now. It’s time to get at least least part of it out on “paper,” in a blog post. So here you go:

Software is, fundamentally, a solid object that is made of knowledge. It follows all the rules and laws of knowledge. It behaves exactly as knowledge behaves in just about any given situation, except that it’s in concrete form. For example, when software is complex it tends to be mis-used. When software is wrong (i.e., has a bug), it tends to cause harm or problems. When people don’t understand some code, they tend to alter it incorrectly. One could say these things of knowledge just as one could say them of software. Bad data causes people to misbehave; bad code causes computers to misbehave. I’m not saying that computers and people can be compared–I’m saying that software and knowledge can be.

One wishes to have knowledge in a sensible and logical form. Similarly, Continue reading

1 Comment

Code Simplicity: The Science of Software Development

What if every software developer could gain the knowledge of long experience without having to go through the pain of repeated failure? What if, instead of being a continuous chaos of complexity and argument, the process of software development could be a sane, orderly progression that was well-understood by every single programmer involved? What if all programmers and their managers shared a common ground for discussing software development decisions–a common ground that was based on facts instead of opinion or authority, and that was actually helpful in deciding what to do on a day-to-day basis with your software project?

What if software development was a science–one with laws, rules, facts, and definitions that told you with certainty which directions to take and which directions to avoid? Not a dogmatic system which restricted you only to some particular methodology, but a series of principles that freed you to think for yourself and make the right decisions for your situation?

What if then, all of this was in a book, that book was only 90 pages long, and it was understandable by every single person working in the software industry, programmer or not? Would it make the world a different place? Find out for yourself: Continue reading


Clues to Complexity

Here are some clues that tell you that your code may be too complex: Continue reading


Developer Hubris

Your program is not important to me. I don’t care about its user interface. I don’t care what its name is. I don’t care that you made it, or what version it is.

The only thing I care about is that your program helps me accomplish my purpose. That’s a truly remarkable feat, and if your program does it, you should be proud. There’s no need to make your program take up more of my attention just because you think it’s important.

Now of course, your program important to you! When you work on code for a long time, it’s easy to become attached to it. It was so hard to write. Your cleverness is unbounded, shadowing lesser mortals in the mountain of your intellect. You have overcome some of the greatest mental obstacles man has ever faced. Truly, you must shout this from the tops of every tower, through the streets of every city, and even unto the caves of the Earth.

But don’t. Because your users do not care. Your fellow developers might be interested, but your users are not.

When you’re truly clever, what will show up for users is that program is awesome. It’s so awesome, the user hardly notices it’s there. That is true brilliance.

The worst offenders against this ideal are programs that pop up a window every time my computer starts. I know your software is there. I installed it. You really don’t need to remind me. If my purpose is to start up my computer so I can use it, how is your pop up window helping me accomplish that? It’s not, so get rid of it.

There are smaller ways to cause problems, too, that all revolve around asking for too much time or attention from the user:

  • “Users will definitely be okay with clicking through three screens of forms before they can use my product.”
  • “I’m sure that users will want to learn all the icons I invented for this program, so taking away the text labels for those icons is fine!”
  • “I’m sure it’s okay to stop the user from working by popping up these dialog boxes.”
  • “Users will totally want to search through this huge page for a tiny little piece of text so they can click on it.”
  • “Why should we make this simpler? That would be a lot of work, and it’s already pretty easy…for me.”

And so on.

The true humility required of a developer is the willingness to remove their identity from the user’s world. Stop telling the user the program is there. Don’t think that the user cares about your program, wants to spend time using its interface, or wants to learn about it. It’s not your program that they care about–it’s their purpose. Help them accomplish that perfectly, and you will have created the perfect program for them.



Open Source Community, Simplified

Growing and maintaining an open-source community depends essentially on three things:

  1. Getting people interested in contributing
  2. Removing the barriers to entering the project and contributing
  3. Retaining contributors so that they keep contributing

If you can get people interested, then have them actually contribute, and then have them stick around, you have a community. Otherwise, you don’t.

If you are just starting a project or need to improve the community of an existing project, you should address these points in reverse order. If you get people interested in a project before you do the later two steps, then people won’t be able to enter and won’t stick around when they do enter. You won’t actually expand your community. So first, we want to be sure that we can retain both existing and new contributors. Once we’ve done that, then we want to remove the barriers to entry, so that interested people can actually start contributing. Only then do we start worrying about getting people interested.

So let’s talk about how you accomplish each step in reverse order: Continue reading


Readability and Naming Things

Many people think that the readability of code has to do with the letters and symbols used. They believe it is the adding, removing, or changing of those symbols that makes code more readable. In some sense, they’re right. However, the underlying principle is:

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

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


The Power Of No

How many times have you used a piece of software that was full of incredibly convoluted features, strange decisions, and unusable interfaces? Have you ever wanted to physically or verbally abuse a computer because it just wouldn’t do things right, or you couldn’t figure out how to make it function properly? And how often have you thought, “How could any programmer think this was a sane idea?”

Well if you’ve ever experienced any of those things, your next thought might have been something like “**** this computer” or “**** the silly programmer who made it behave this way”. After all, aren’t programmers and hardware designers to blame for the crazy behavior of the system? Well, yes, to some extent they are. But after being intimately involved in software design for many years, I now have another reaction to poorly-implemented features. Instead of becoming angry with the programmer who implemented the system, I ask myself, “Who was the software designer who authorized this feature?” Who stood by silently and let this feature happen when they had the power to stop it?

Granted, sometimes there is no software designer at all, in which case you’re practically guaranteed to have a broken system. But when there is a software designer, they are ultimately responsible for how the system is put together. Now, quite a bit of this job involves designing the structure of features before they go into the system. But there’s also another part of the job of a software designer–preventing bad ideas from being implemented. In fact, if there’s any lesson I’ve learned from my years in the software industry, it’s this:

The most important word in a software designer’s vocabulary is “no”.

Continue reading