Still searching Google before going straight to the code?

It happens to all of us. A lot. You hit a wall. Maybe you don't know how to use a certain method, it's not behaving the way you expected, you don't know what arguments to pass, something like that. We all run into this daily.
For a good while, my first instinct was to search my exact problem on Google, hoping that someone on StackOverflow had already asked this question and the answer was waiting for me. Occasionally, the stars would align and I would find this answer. But often, my search would turn up nothing, or worse: it would return issues that seem related, but really aren't. So I'd end up wasting time reading about things that don't apply.
Nowadays, I always go to the source code first. Why? Because it has all the answers!
Before I talk about why I go to the source first, I'm going to show you the tools I use for doing so. These tools usually make it more convenient to go to the source instead of searching the web.
1. bundle open
I checked my shell history, and I run bundle open <gemname> pretty often.
This really only applies if you're using Bundler, but there's a good chance that you are. Run bundle open <gemname> to open up the source code of a gem in your $EDITOR. This goes great with a search tool (like grep, ack, etc) so you can quickly search through the gem for whatever you're looking for.
Sidebar: I've been using the Silver Searcher in place of ack or grep for all my searching needs lately. It's noticeably faster than the alternatives.
Once you've opened the source of the bundled gem, you can actually modify the files. The next time you run your tests or development server, you'll see the changes. This can easily backfire, but I make use of it all the time to print debugging statements inside third-party code that don't understand.
So, bundle open is great for stuff in your current bundle, but what about other code you depend on?
2. qwandry
qwandry is a gem that allows you to open the source of any gem or anything in the standard library. This is what sets it apart from bundle open.
Let's say you're using the tempfile library and you're not understanding what the heck it's doing. You can run qw tempfile and it will open tempfile.rb from the stdlib right in your $EDITOR.
3. gem_readme
This one isn't quite the same as the others. README files are often a gold mine of information about a particular project. A such, I've always found it useful to look at the README before going too far down the rabbit hole.
For this, I use the gem_readme gem. Once you've got it you can do gem readme resque to page through the Resque README right in your terminal.

4. ctags

I left this one until last because it's the most useful, but potentially the most difficult to get set up. I'm certain that you've heard of ctags. If you haven't yet taken the time to set it up, at least give it a try.

I can't give instructions that work everywhere, because each editor supports tags in a different way. Some quick googling should turn up the answers for your editor pretty fast. For me, the best combination has been 
gem-ctags and AutoTag.
At this point you might be saying:
But Jesse, when I need help, I just search Google for rdoc.
First of all, you should use ri instead. Second of all, I always find it more enlightening to look at the source code directly. This is for a few reasons.
1. Documentation doesn't tell the whole story.
ActiveRecord is a great example of this. When I'm trying to figure out what touch orreload or some other ActiveRecord::Base method does, I could look at the documentation. It would tell me how the method is intended to be used, what parameters it takes, and what it returns.
In most cases, this is all you need. But if you've got a weird bug, or you want to know how a given method interacts with the database, you've got to go to the code. Once you do, you'll see that the reload method is defined several times in different modules that call each other, tacking on different behaviours. This is something that the documentation didn't make clear.
If you want the whole story, go to the source.
2. Tests are often the best documentation.
As a community, we Rubyists love tests. It's always great to see that a gem you're using has tests, this gives you more confidence that the implementation is correct and maintainable.
But when you're trying to figure out how to use an API, often the tests will reveal more than the documentation. Why? Automated tests are a consumer of the public API! Most often, they're the consumer that really pushes the edge cases and shows what is, and isn't possible, with the public API.

3. You learn new things!

Other people use different styles and different approaches than you do. Reading through their source code will inspire new ideas for you to try.
That's about all the ranting I'll do for today. In summary:
  • When you hit an issue, use bundle open, qw, or ctags to go right to the source.
  • If you can't figure things out from the implementation alone, look to the tests next.
  • If all that fails, look (or ask) for help online.
I hope this email helps get back some of those inevitable wasted cycles when you're coding.

Until next time,
~ Jesse

comments powered by Disqus