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

Cells.py a terrible temptation

Terrible, terrible temptation.

Today on HN phreeza posted an awesome python game called Cells.

I forked the project and began looking through it. Made some comments (seriously, fork it yourself and add comments. It needs it). Tried to think of ways to implement the TODOS. Popped open a buffer and began brainfarting a testsuite/profiler for it.

And then caught myself. This month is Ruby. Why am I plunging into Cells, even though it is undoubtably dripping with awesome sauce?

I can tell myself that there's plenty of time to do both. But that'll mean that the next cool code I want to jump into will be ever so much more distracting.

Solution: set up a cronjob to fetch the upstream repo once a week until I can dedicate myself to playing with it. When I jump back in, it'll be even more awesome (since the post on HN, it's already had a ton of contribs).

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.