Reading gems’ source code

Posted on Updated

Countless times I have found it useful to read a gem’s source code. When you can’t find the answer in the documentation, you need to read the code. 

You can run bundle open $gem_name in your project’s directory to see the source of a gem. 

I prefer using this method instead of reading the code in GitHub because:

  • You can use your preferred editor. This is very useful for navigating across files. This type of task requires lots of jumping around the codebase because you aren’t familiar with it. You need to set the EDITOR or BUNDLER_EDITOR environment variable, so your favorite editor can be used to “open the gem.”
  • You can open the specific version of the gem you are using. Doing that in GitHub requires browsing through the tags/releases to find your desired version. 

I have found bundle open invaluable in the following situations:

  • Learning how to use a gem when there isn’t documentation;
  • Learning about the implementation details of specific functionality so I can understand its limitations;
  • Understanding the root cause of odd behavior when using the gem;

You run gems in production along with your code. Therefore, it’s natural for situations in which you need to be deeply acquainted with gems to occur.

Navigating the code of a 3rd party gem may seem intimidating. It is similar to navigating parts of your codebase that you aren’t as familiar with. I don’t have any actionable tips for this, but here are some observations:

  • I start with a question I want to answer (e.g., How is this method implemented?). Having a question is important because it gives you a starting point. This means I can start by reading the class/methods related to the question and work my way from there. 
  • The source code of gems typically has comments explaining what each method does. This information is valuable. Some gems have more useful comments than useful README.md.
  • Most gems are small, so you can quickly find what you need. I found it useful for larger gems to take notes of my observations/findings, so I don’t get lost.

I can send you my posts straight to your e-mail inbox if you sign up for my newsletter.