Readable Code

I've released a lot of code over the years, but I haven't done a very good job of making sure it's good. In fact, most of it's junk because I've always focused more on getting interesting results than writing code that's readable. I've always been careful to format code to have consistent style, but I haven't always written comments where they're needed, and general documentation has usually been non-existent (outside certain literate programming experiments).

Now that I've made a full time job of teaching old code new tricks at Smule, I appreciate well-written comments and I understand that documenting the way I intend modules to be used is crucial. Discovering best practices and using them consistently means you can guess how a module will work without reading anything.

In light of these realizations, I've spent a significant amount of time improving the usability of my two biggest projects right now: ckv (a Lua-based audio programming language) and ruck (a strong timing library for Ruby). I write copious documentation, and hone APIs by writing clear client code first, then iterating. I've tagged important milestones as releases, and in the case of ruck, synchronized release numbers with all the gems that rely on it. It should be easier to understand these two projects than anything I've written before (though as invisible as I am, it's difficult to test this hypothesis).

Safe code is still boring code, but if you've seen any of my ruck commits lately, you know I haven't changed my opinion on that one bit. ;)

I'm alive!


Comments

Click here to view the comments on this post, or just send me an e-mail.