Nowadays I’ve checked out the archives of Jeff Atwood’s Coding Horror blog, and found this highly recommended title. I remember a few years ago I read Don’t Make Me Think, and intended to read The Design of Everyday Things that time as well, but somehow forgot it.
I must confess that I had to force myself to read the book. It’s not a long read, probably 300 pages (I do my readings on Safari Books Online, with my Kindle, so page numbers don’t come into play anymore), and there is vast knowledge and practical advices but they are more like isles, separated with oceans of text.
Anyway this book made me realize just how awful designs I used to make (and of course, still make every now and then). By designs I mean my class-hierarchies and APIs that my “users” (who happen to be my co-workers) have to use. This revelation came when reading the book’s most important statement: when people can’t operate “everyday things” then it’s not they who are at fault, rather than the design of the device in question. Well, in software development code is pretty much an “everyday thing” and I’m certainly through some frustrating conversations about how exactly some of my classes should be used. And sadly, common sense didn’t make me realize that if I need to explain something then the issue doesn’t necessarily lie in the other party’s incompetence.
One might argue that source code is definitely not an artifact that’s for everyone, and whoever writes it must be educated and competent enough to be able to make sense from it, and he would be definitely right. The point is, which is well emphasized in the book, that anybody can operate a door, use a word processor, or perform other similar tasks, but mostly people are inclined with what they want to do, not the how, so you should make it as easy as possible. This is also holds true in my case as a software developer. Consider the following code, first stage of yesterday:
I bet you spot the obvious problem, how on earth do we know what 1000 represents? Well, you can just hit F12 in Visual Studio and try to figure out how I treat that value, can’t you? OK, let’s take it a step further, and document our work:
Much better, isn’t it? Well, not really that comment is destined to get out of sync with the code. I could improve the documentation of the attribute class, adding code comments for the constructor of the attribute taking that parameter, but I think we can agree that there is a better way. I’ve come up with this in the end:
I think you can’t really do more to prevent others screw up with the usage of this attribute. I must mention that documentation is in place in the class, so Visual Studio IntelliSense will grab and presents it. The point is that now the code tells what it does about itself, so you don’t have to read the documentation. Sure, there was some extra work, like creating an enum for storing time values, thinking on a more expressive name, etc. But I only have to write this class once, and it will be used thorough the application.
This is the philosophy I learned from The Design of Everyday Things.