Reading Ruby Methods in Documentation:

A Guide for New Developers

Patrick Santucci
Apr 27 · 7 min read

Part of learning to code is learning how to talk about software

There’s an odd lag between writing your first tiny pieces of software and meaningfully understanding the language of programming — not Ruby (or whatever your flavor is), but the language we use to describe what’s happening in code, the tools we have, and what we want software to do for us. If hash, array, method, or class recently took on new meanings in your vocabulary, this guide is for you!


Reading the documentation often saves headaches, saves time, and saves the day

Almost every developer will someday look to Stack Overflow for answers on how to do something new in code. Stack Overflow is an incredible source of knowledge and expertise, and with a simple Google search, you can nearly always find a ton of already-written code that almost solves the problem you need to solve! Unfortunately, it doesn’t come with a posted sign reading HERE BE DRAGONS 🆘.

Often, using a pre-made solution to a problem that’s nearly the same as yours is a lot like blindly following the directions after you shouted your destination to Siri through a mouthful of peanut butter. You’ll certainly go somewhere, but it might be to Nebraska’s best fungal cream shop, Dandy Mould, not Disney World. Much the same, your borrowed code may return the result you expect, but inside of a hash instead of an array, for example.

Instead, we need to understand what the code needs to work, how it’s going to get us there, and what it’s going to give us back at the end. We can break down any code by using Ruby-doc to understand what’s going on!

I recognize these words, but what are they doing here? 🤯

At a glance, Ruby-docs are chock full of information — they use technical terminology that is usually unfamiliar to beginning programmers. This isn’t to deter you. Rather, it’s done with the understanding that eventually, you’ll be able to read the documentation and get all of the information you need from one quick, action-packed sentence.


A practical example, #Array.zip, in plain English 🇬🇧

Let’s take a look at what might be an unfamiliar method, #Array.zip:

Taken from Ruby-Doc 2.6.1

Let’s translate Ruby-doc step by step, using this example:
[‘a’,‘b’,‘c’].zip([1,2,3])

Converts any arguments to arrays, then merges elements of self with corresponding elements from each argument.

1) #Array.zip combines two or more arrays. It must be run on an array, but if it is given something that is not an array, it will convert it to an array and combine it with the first array (the one that #zip is being run on). In our example, [‘a’,‘b’,‘c’] will be ‘zipped’ with [1,2,3].

This generates a sequence of ary.size n-element arrays, where n is one more than the count of arguments.

2) It counts up the number of items in the original array, and creates that number of new arrays (looking at our original array, [‘a’,‘b’,‘c’], that’s three new arrays). It then adds the first item from each array that we’ve asked it to combine to the first new array, the second item from each array to the second new array, and the third item from each array to the third new array, and so on.

The documentation lets us know that when it’s finished, we can expect the number of items in each array to equal the number of arrays we fed in, plus one (to account for the original array).

For our example, that means we’re going to have three arrays that have two items each.

This means that our new set of arrays looks like this:

[‘a’,1]
[‘b’,2]
[‘c’,3]

If the size of any argument is less than the size of the initial array, nil values are supplied.

3) What if one of our arrays is too short? Remember that in step 2, #zip looks at the length of the array it’s being run on, and creates that number of new arrays. If we have three new arrays, but we’re only combining the original with an array of two items, it will insert nil for any extra new arrays.

If we changed our example to be [‘a’,‘b’,‘c’].zip([1,2]), it will look like this:

[‘a’,1]
[‘b’,2]
[‘c’,nil]

If a block is given, it is invoked for each output array, otherwise an array of arrays is returned.

4) Finally, if we run Array.zip with a block of code in curly braces, it will run that code on each of the new arrays, the same way as if you’d run #Array.map.

If you don’t provide a block of code (like we didn’t in our example), #zip will add each of the new arrays it created into one big array and return the big array, which would look like this:

[[‘a’,1],[‘b’,2],[‘c’,3]]

And that’s #Array.zip! 🎉

You can see that writing it out in plain English takes a lot longer, so there’s an upside to being able to understand the more technical terminology. However, especially in your early days of coding, it can be really helpful to translate the documentation entries into plain English so that you develop a firm grasp of what the method is actually doing.

The documentation gives us a shortcut to know what we’ll get out of a method

Now that you understand what #Array.zip is really doing, we can look at the code snippets Ruby-doc provides to explain. First, there’s the method’s header:

Looking at this piece by piece:

You’ll note that the method just dives right in with zip; we found this on the Arrays page in Ruby-doc, so we know that this method actually needs to be run on an Array, like this: my_array.zip(arg,…).

This header shows us that zip can be run with more than one argument. See the (arg,…)? That ‘’ indicates that you can add as many arguments as you want, meaning that you can combine as many arrays as you need to in one go. If we could only add one, like in some other methods, it would be written zip(arg).

There are two lines in this header though! This is because as we discussed in step 4, #zip will return a big array of smaller arrays if we don’t give it a block, but if we do give it a block {in curly braces}, it returns nil. Instead, we’d get back whatever the code in our block returns.

Ruby-doc shows us real examples using the method, and what it returns

Using what we’ve learned above, we can pretty much read this code out loud!

  1. Create an array a = [4,5,6]

Don’t fear the Ruby-doc!💪

This is just one example of some of the great functionality built straight into Ruby. If you can break down the documentation into plain English, you can start to use some of the more advanced features of Ruby — you’ll find that many of the times you’ve said to yourself “I wish there was a way I could just get this to look like that”, there’s a method just waiting to be found.

Some common gotchas to look out for:

  1. “Returns an enumerator if no block is given”
    You’ll see this warning on most enumerator methods. First, think about what an enumerator does; these are methods like each, select, or map, that enumerate each item in a set (like an array or a hash) and then do something to them. That something is the code we write in a block. So this is Ruby-doc’s friendly reminder that if you don’t tell it what you want to do to each enumerated item, you won’t get back what you’re expecting from this method.

Using the documentation has consistently made my code more dynamic, and helped me write more effectively by leveraging the pre-built capabilities of Ruby. As you stare down the long, dusty road of repeated manipulations of an Object, take a look at Ruby-doc. It may well save you a trip 🏖

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade