Code Simplicity

Code Simplicity

There Is No Science Of Software

by Max Kanat-Alexander
Published on February 19, 2008

What we think of today as being “computers” started out in the minds of mathematicians as purely abstract devices–thoughts about how to solve math problems using machines instead of the mind.

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. Keep Reading

Simplicity and Strictness

by Max Kanat-Alexander
Published on February 13, 2008

As a general rule, the stricter your application is, the simpler it is to write.

For example, imagine a program that accepts only the numbers 1 and 2 as input and rejects everything else. Even a tiny variation in the input, like adding a space before or after “1” would cause the program to throw an error. That would be very “strict” and extremely simple to write. All you’d have to do is check, “Did they enter exactly 1 or exactly 2? If not, throw an error.”

In most situations, though, such a program would be so strict as to be impractical. If the user doesn’t know the exact format you expect your input in, or if they accidentally hit the spacebar or some other key when entering a number, the program will frustrate the user by not “doing what they mean.”

That’s a case where there is a trade-off between simplicity (strictness) and usability. Not all cases of strictness have that trade-off, but many do. If I allow the user to type in 1, One, or " 1" as input, that allows for a lot more user mistakes and makes life easier for them, but also adds code and complexity to my program. Less-strict programs often take more code than strict ones, which is really directly where the complexity comes from.

(By the way, if you’re writing frameworks or languages for programmers, one of the best things you can do is make this type of “non-strictness” as simple as possible, to eliminate the trade-off between usability and complexity, and let them have the best of both worlds.)

Of course, on the other side of things, if I allowed the user to type in O1n1e1 and still have that be accepted as “1”, that would just add needless complexity to my code. We have to be more strict than that.

Strictness is mostly about what input you allow, like the examples above. I suppose in some applications (like, say, a SOAP library), you could have output strictness, too–output that always conforms to a particular, exact standard. But usually, it’s about what input you accept and what input causes an error.

Probably the best-known strictness disaster is HTML. Keep Reading

When Is Backwards-Compatibility Not Worth It?

by Max Kanat-Alexander
Published on February 11, 2008

This title might seem a bit like a contradiction to my last post! Well, you really shouldn’t break your API, if you can help it. But sometimes, maintaining backwards compatibility for any area of your application can lead to a point of diminishing returns. This applies to everything about a program, not just its API.

A great example of the backwards-compatibility problem is Perl. If you read the perl5-porters summaries with any regularity, or if you’re familiar with the history of the Perl internals in general, you’ll have some idea of what I mean.

Perl is full of support for strange syntaxes that really, nobody should be using anymore. For example, in Perl, you’re supposed to call methods on an object like $object->method(). But there’s also a syntax called the “indirect object syntax” where you can do method $object. Not method($object)–only the case without the parenthesis is the indirect object syntax.

Really, nobody should be using that syntax, and it’s not that hard to fix applications to call their methods the right way. And yet that syntax is maintained and supported in the Perl binary to keep backwards compatibility.

Perl is full of things like this that block forward progress because of historical problems.

Now obviously, this is a balancing act. Keep Reading

Ways To Create Complexity: Break Your API

by Max Kanat-Alexander
Published on February 7, 2008

An API is a sort of a promise–“You can always interact with our program this way, safely and exactly like we said.” When you release a new version of your product that doesn’t support the API from your old version, you’re breaking that promise.

Above and beyond any vague philosophical or moral considerations about this, the technical problem here is that this creates complexity. Keep Reading

What Is Overengineering?

by Max Kanat-Alexander
Published on January 29, 2008

Software developers throw around this word, “overengineering,” quite a bit. “That code was overengineered.” “This is an overengineered solution.” Strangely enough, though, it’s hard to find an actual definition for the word online! People are always giving examples of overengineered code, but rarely do they say what the word actually means.

The dictionary just defines it as a combination of “over” (meaning “too much”) and “engineer” (meaning “design and build”). So per the dictionary, it would mean that you designed or built too much.

Wait, designed or built too much? What’s “too much”? And isn’t design a good thing?

Well, yeah, most projects could use more design. They suffer from underengineering. But once in a while, somebody really gets into it and just designs too much. Basically, this is like when somebody builds an orbital laser to destroy an anthill. An orbital laser is really cool, but it (a) costs too much (b) takes too much time and (c) is a maintenance nightmare. I mean, somebody’s going to have to go up there and fix it when it breaks.

The tricky part is–how do you know when you’re overengineering? What’s the line between good design and too much design?

Well, my criteria is this: When your design actually makes things more complex instead of simplifying things, you’re overengineering. Keep Reading

How Simple Do You Have To Be?

by Max Kanat-Alexander
Published on January 25, 2008

Sometimes, when you’re working on a project, there’s a question of, “How simple do we really have to be?” “How much do we have to simplify this thing?” “Is it simple enough?”

Well, of course, simplicity is relative. But even so, you can still be more or less simple. From the relative viewpoint of your user, your product can be hard to use, easy to use, or somewhere in between.

So, how simple do you have to be?

Honestly?

If you really want to succeed? Keep Reading

Complexity Is a Prison

by Max Kanat-Alexander
Published on January 22, 2008

Sometimes, I think, people are worried that if they make their code too simple, then either:

  • Somehow they’re not demonstrating how intelligent they are, or how valuable they are, to their managers, or
  • The project will become so simple to work on that anybody can just steal their job!

It’s almost as though if they actually did their job right, then they’d lose it. Now, stated that way, that’s obviously a nonsensical viewpoint. But, if you’ve ever worried about it, here’s something to think about:

What if your code is so complex that you’ll never be able to leave your job? Keep Reading

Purpose and Simplicity

by Max Kanat-Alexander
Published on January 18, 2008

A fast way to get complicated is to violate the purpose of what you’re doing.

For example, what’s the purpose of a web page? To give and receive information. Mostly to give information, and then some websites also take information, such as when you’re buying something.

How many complicated web pages have you seen that think they’re doing something else than giving or receiving information? Maybe they think they’re being entertaining, or something. I don’t know what their designers were thinking, but they probably weren’t thinking about giving or receiving information. Instead they’re hiding their information in a complicated mass of pictures and shapes.

Usually, the basic purpose of any given thing you’re working on is pretty simple. But if you add to that purpose, things can get complex pretty fast! For example, the basic purpose of Bugzilla is to store and organize bug reports. If we suddenly made Bugzilla also able to read your email, it would get ridiculously complicated. (Not that Bugzilla is the simplest program in the world, but we’re working on it.) Can you imagine what the UI would look like? Where would we put all the buttons? That would be a violation of Bugzilla’s purpose.

It’s also important to think about user’s purpose. Keep Reading

Simplicity Is Relative

by Max Kanat-Alexander
Published on January 16, 2008

Defining “simple” really depends on your target audience. What is simple to me might not be simple to my mother, or my friends. Also, when I create something, it’s always relatively “simple” to me, because I understand it inside and out. But to somebody who’s never seen it before, it might be very complicated.

This is why in VCI I put a big, obvious section of documentation near the top called “New To VCI?” And then it contains some simple, obvious steps to take. It’s written as if the reader knows nothing about VCI, because if you’re new to something, you probably don’t know anything about it.

I see way too many software projects mess this up. You go to read the documentation, and you’re presented with a huge mass of links and no direction. This is simple to the long-time developer of the project, because a page with lots of links lets that developer quickly go to the part they’re looking for. But for the new person, it’s complicated. On the other hand, for the long-time developer, adding a page with big, simple buttons and eliminating that list of links would add to the complexity of his task, because he’s just trying to find a very specific thing very fast in the documentation.

The only thing worse than complex documentation is no documentation, where you’re just expected to figure it out for yourself or “already know.” To the developer, the way his program works is obvious, but to the new user, it’s totally unknown.

With software, there are all sorts of different viewpoints. Just a few would be: Programmer, QA Engineer, Manager, Support Technician, User, Power User–to all of these people, “simple” will be different.

Context has a lot to do with this too. Keep Reading

Designing Too Far Into The Future

by Max Kanat-Alexander
Published on January 14, 2008

There is only a certain amount of the future you can know. You can know with some certainty that you’ll be breathing in the next few minutes. You can know with some certainty that if you go out to your car and push the gas pedal, the car will probably go somewhere.

The brighter somebody is, the better they can accurately predict the future.

However, no matter how smart somebody is or how much they know, there are some things about the future that you can not know.

In programming, the biggest thing you can’t know is how your program will change in the future. You can know that it will change–that’s guaranteed. But how it will change five, ten, or twenty years from now, we just don’t know.

A common mistake that developers make is designing too far into that unknown future, making too many assumptions about it. Everybody’s done it, probably. I’ve done it. You set up some huge, rigid framework and plan, and you get started setting it up, and either:

  • It doesn’t work and you have to re-write it all, or
  • Large parts of it never get finished, and then there are little useless pieces sitting around in the code that were “going to be used” but never were, or
  • After years of work you find that you’ve designed yourself into a hole and have to re-write the whole thing.

I did that once, in Bugzilla, in a simple but stupid way. Keep Reading

Previous 1 … 6 7 8 9 Next
  • Home
  • Contact
  • About
  • Book: Understanding Software
  • Book: Code Simplicity

Max Kanat-Alexander Follow

mkanat
Retweet on Twitter Max Kanat-Alexander Retweeted
January 10, 2023

@__mharrison__ I did.

I would've read Kanat-Alexander's "Code Simplicity" sooner.

I truly think it may be the most crucial code learning resource there is.

I'm thankful for all other books. They give information/knowledge about usage of tools. Code Simplicity, however, teaches wisdom.

Reply on Twitter 1612846495056945152 Retweet on Twitter 1612846495056945152 1 Like on Twitter 1612846495056945152 21 Twitter 1612846495056945152
Retweet on Twitter Max Kanat-Alexander Retweeted
December 9, 2022

@mkanat just ended reading "Code Simplicity", great ready: simple and easy to understand, just as code is meant to be! 👌🏼

Reply on Twitter 1601103831101685761 Retweet on Twitter 1601103831101685761 1 Like on Twitter 1601103831101685761 1 Twitter 1601103831101685761
December 7, 2022

Sometimes you have to choose whether to be “nice,” or actually say “no” to doing the wrong thing. Keep in mind, it is not actually kind to deliver bad products to all your users, just so you can be “nice” to one person.

Reply on Twitter 1600448041848229888 Retweet on Twitter 1600448041848229888 Like on Twitter 1600448041848229888 4 Twitter 1600448041848229888
November 15, 2022

It's always important to understand your users and the problems they actually have.

In developer tools, it's easy to assume you already know the problems, because you're a developer. But often, it's surprising to discover what developers' actual pain points and requirements are.

Reply on Twitter 1592626294474559488 Retweet on Twitter 1592626294474559488 Like on Twitter 1592626294474559488 11 Twitter 1592626294474559488
Retweet on Twitter Max Kanat-Alexander Retweeted
November 15, 2022

How does LinkedIn approach developer productivity?

In this week's issue, @mkanat shared his learnings from spending ~20 years in this field, and how LinkedIn approaches this area.

Subscribers can read the full issue here: https://newsletter.pragmaticengineer.com/p/linkedin-engineering-efficiency

Reply on Twitter 1592567547718553600 Retweet on Twitter 1592567547718553600 11 Like on Twitter 1592567547718553600 107 Twitter 1592567547718553600
  • Home
  • Contact
  • About
  • Book: Understanding Software
  • Book: Code Simplicity