Browsing erb.rb, part 1

Today's installment of One Month Codebase is a short browseof Masotoshi Seki's ruby/lib/erb.rb

It's 902 loc, not that hefty, and as we'll see, rather straightforward.

First, the introductory comments. The first 255 lines are great documentation. Several examples showing off different aspects, clear writing. It should make your day.

Pop open a buffer and type in these examples. They may seem trivial, and you really want to get to the meaty bits. Do it anyway. It may turn out that the example usage contains a bug, in which case in a few minutes you could contribute back to the project. If the code works, the sheer act of typing it out, running it, debugging your typos etc, will doubtless put you in the mindset of wondering where you can use

this technique. Hell, halfway through this you may have a brainfart that turns into a full project. At the very least, you will be accomplishing the important goal of playing with the code.

A good idea is to take one pomodoro (half an hour) per example. Keep another buffer open to jot down thoughts so you can come back to them later.

Now that you know how erb.rb is used, you can see how it works. Give yourself half an hour to skim the code, noting in a buffer points of interest, oddnesses, places where you need more comments. A good rule of thumb is that you should make a note of any oddly long method or class. These long methods and classes are great places for improvement: they're ripe to be refactored and simplified. Make a note

of any class or method that seems to be doing too many things, and ask yourself why it absolutely shouldn't be broken up. Sometimes there's a good reason, other times you will be saving countless people from horrible frustration.

Time: 1 pom

One month codebase: getting started

Read the Github guide on forking.

Good. Now if you want to follow along with my one month codebase project, you know how to do it easily. This month, I'm reading Ruby.

Now you have a shit ton of files and directories. Your goal is to grok them. And then improve them.

Now, you could have just cloned the repo directly, and gone abrowsing through the code. Don't do that. It makes things harder when you find bugs, typos, etc, to contribute a fix. Fork it, keep the codebase current, and push all your changes. The goal here is to not just read the code, but to learn what it's doing. That means getting your hands dirty and then leaving a trail of grubby handprints all over the code.

Optparse.rb is a good example of what you'll find: fine documentation and introduction, with scattered bits of undocumented and initially terrifying magic. Kind of like having sex for the first time.

ruby/lib

Before leaving for work, I'm spending an hour or two reading 3 random ruby/lib files:

observer.rb
benchmark.rb
optparse.rb

One hour is plenty of time to skip around a file, following ctags, getting a sense of its structure. There's even time to dive into hairy methods like #summarize and tweak out their logic.

While reading the code in vim (it is great for reading code, especially with NERDtree), I've got an emacs open to experiment with, comment on oddities, and run tests.

Try it. While reading the code, yank a method into its own file, and try to break it. Create your own unit tests, and see how hard it is to change the method without regression. Ideas that come to you while puttering about breaking things? Pop open a .org buffer and scribble them for later.

The important thing is not to approach it like a Google whiteboard interview. You don't need to memorize the entire damn file. Just figure out how it works, where it hides its superpowers, and what its weaknesses are. Once that's done, you've gotten halfway to being able to improve it and push your contributions to the project.

One Month Codebase Project

2:chaitin~/srcs% ls

arc/  conkeror/  ezbl/  git/  jquery/  mongoDB/  ruby/  slime/  tags  unix-jun/  uzbl/  xmonad/

I've already got a bunch of cool code I read. Nowhere near enough, though. 

If you don't already have a habit of reading code for fun, do it. You'll thank yourself for discovering something not only more meditative than zazen, more frustrating than slamming your genitals in a drawer, more addictive than sudoku, and more productive than NetHack, but also more fun than masturbation. Reading good code is like being Sherlock Holmes in the moment of solving a crime. Reading bad code is like being Watson as he watches Holmes repeatedly harpoon a pig carcass, wondering why the fuck didn't he look around for a better apartment. Both will teach you.

Previously, I've been skipping around willy nilly. A few hours reading one file in one repo, getting a bit of a hang of it, then switching to something else that interests me. In keeping with my effort to prevent getting distracted by projects and shiny closures, I'm trying out something. 

Each month I'm going to focus on one codebase. By the end of the month, sans distracting forays elsewhere, I will know that codebase better than I would previously have. Maybe even better than others who divide their time, skipping the begats across repos.

This month, it's Ruby. 

I'll post more on it later. Thanks to Oscar for providing the impetus to get my shit in gear.

Projects: Rave and Ruzbl

I've started some projects, and will start pumping them to github shortly (once I've got my testing workflow tweaked and automated enough not to let me screw up too badly). I'll post my testing setup once I've Hofstadterianly worked out its kinks.

Rave. A livecoding environment inspired by Topher Cyll's Practical Ruby Projects, with emacs integration. Plenty of space in which to play around. Look at mature livecoding projects like Impromptu, and you'll see there's boundless room for tweaking.

Ruzbl. An FXruby scaffold around uzbl. Uzbl-tabbed is simply not cool enough. I don't want tabs, I really want the sheer flexibility I expect from Xmonad and GNU Screen. I want to xmonadify uzbl: provide a terse and powerful way to tile, tab, and otherwise manipulate uzbl instances. Imagine how cool it'd be to have an uzbl layout that can tile, group by parent window or category...