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.
1Let’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 methodNow 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 returnsUsing what we’ve learned above, we can pretty much read this code out loud!Create an array a = [4,5,6]Create an array b = [7,8,9]Zip [1,2,3] to a and b, like this:[1,2,3].
zip([4,5,6], [7,8,9])This returns [[1,4,7], [2,5,8], [3,6,9]].
Now, try [1,2].
zip(a,b) instead.
This returns: [[1,4,7], [2,5,8]]With this example, Ruby-doc is showing us that if we zip a short array with longer arrays, the longer arrays’ extra items will be left out.
This one’s a bit more confusing, but we can still read it.
We’re going to zip a to an array [1, 2], and an array of just [8].
This looks like:a.
zip([1,2],[8]Because these are shorter than the original array, #zip fills in nil for the extra values, resulting in:[[4, 1, 8], [5, 2, nil], [6, nil, nil]]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:“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.
The exclamation point!No, this doesn’t mean “again, but this time with feeling” — the difference between map and map!.is that map creates a new array based on your block, while map!.overwrites the original array you passed in with what was in your block.
Many methods have both apathetic and excited versions, where the excited version overwrites the Object that the method was run on.
Use with caution!Finally, remember what type of Object you’re working withRuby-doc has a page for each of the built-in Object types, and all of the native methods that you can use on them out of the box.
At a glance, I have the pages for Array, String, Enumerator, Hash, and DateTime open for quick reference.
Defeat those NoMethodErrors by ensuring that you’re using the right methods for your object!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 ????.. More details