Readable Code

I attended 2016's Full Stack Toronto. One of the talks I attended - one for which I had very low expectations - was "Impactful Refactors: Refactoring for Readability," presented by Kinsey Ann Durham. As it turned out, it was the most memorable and possibly the best talk of the conference. One of my favourite maxims of hers was "leave the code better than you found it:" ie. if you find a readability problem you can solve reasonably easily, do the refactor. She had another pronouncement that I can't agree with though: she thought that comments should be unnecessary, they're an indication of "code smell." Seriously? You are young. And probably a Ruby programmer (not to belittle Ruby ... I guess I'm implying that it's more readable than most).

She recommended several resources related to the various ideas she'd presented, and within a day I'd placed a hold at the library for O'Reilly's The Art of Readable Code (Dustin Boswell and Trevor Foucher, 2011), which is a really good book. While I'm not finished it yet, it's a remarkably fast read for a tech book. Much of it is articulating stuff that seems like common sense when you read it, but ... maybe you hadn't quite thought it through yet. One of the best of many good ideas they put forward is "The purpose of commenting is to help the reader know as much as the writer did." My favourite example of this - which I've run into in real life on numerous occasions - is when you choose a more difficult route/algorithm to a solution than the obvious. If you don't comment it, the next person along (or possibly even you, six months from now) will attempt to "optimize" the code and discover what you already knew - that that optimization doesn't work or introduces unacceptable compromises.

As mentioned, this is a relatively easy read as tech books go - and it doesn't really require much in the way of programming experience, nor is it aimed at any particular language. But you won't appreciate it until you've been coding for a while - until you've had to read someone else's code, or found some uncommented abominable hack in your own code a year after the fact. Then you begin to appreciate just how important clean and readable code really is.

I've always tried to write clean and readable code ... and I know I often fail. I hope to fail a bit less with this in my mind, a clear codification of the rules of clean code by a couple people who've obviously thought about it a lot.