"The Art of Readable Code" - Book Review

The Art of Readable Code, Boswell, Dustin and Trevor Foucher. O'Reilly, 1st ed.

Some of this is similar to my recent (and directly related) blog entry on readable code.

The Full Stack Toronto conference was October 17th and 18th, 2016. I attended a talk by Kinsey Ann Durham called "Impactful Refactors: Refactoring for Readability," which turned out to be an excellent talk on a number of methods for improving code readability. My favourite suggestion of hers was that programmers should "leave the code better than you found it" - kind of a Boy Scouts motto for programmers, but that doesn't make it any less valid. She also quoted Justin Searls (very appropriate to this book review): "Your clever code makes me feel stupid."

Among her resources listings was The Art of Readable Code. I was holding one of the library's copies within three days of her presentation. Most of their suggestions come across as totally common sense: they're often things you've probably thought about as a programmer, and have started to work out ... but you probably haven't gone as in-depth, or worked it out as well as they have. And you probably haven't thought of everything they cover in the book!

The book is easy to read - the ideas are simple, and the code examples are fairly straight-forward. In fact, it would make sense to a beginning programmer in any language. But it would have very little impact. Ideally, this should be read by journeyman programmers, people who have been programming for at least a couple years and who have had to maintain someone else's code. This book is meant for people who understand what a mess code can be, who have experienced first-hand wading through a complex program they (or someone else) wrote a year ago. That's when you'll really appreciate the book.

I'm going to put some of their best ideas here, although I'm not sure how effective they are out of context. They all seem like damn good ideas to me.

  • Code should be written to minimize the time it takes for someone else to understand it
  • Pack information into your names [variables, functions, etc.]
  • It's better to be clear and precise than to be cute
  • If you're going to use a generic name like tmp, it, or retval, have a good reason for doing so
  • Shorter names are okay for shorter scope
  • Actively scrutinize your names by asking yourself, "What other meanings could someone interpret from this name?"
  • Aesthetics:
    • use consistent layout, with patters the reader can get used to
    • make similar code look similar
    • group related lines of code into blocks
  • Consistent style is more important than the "right" style [eg. you may know tabs are "right," but if the company policy is spaces, use them]
  • the purpose of commenting is to help the reader know as much as the writer did
  • etc.

Highly recommended.