Hi!

Busy weekend. Wordstock. Reading. I SHOOK TIMOTHY ZAHN’S HAND.

But I’m not going to talk about that. I’m going to save that for another post, for a time when I’m not prepping for a couple of job interviews. No, today I’m going to talk about a lynchpin of coding:

Documentation.

Specifically – and this is going to be brief – the importance of not just screwing around with variables in hashes and arrays in Ruby. See, I’m refreshing my memory on this thing (and learning some new stuff!) by going through the courses on Codecadamy. I’ve been doing this with JavaScript, but I’ve decided that I like Ruby better. Possibly because it’s my birthstone. I think. (That’s what it is for July, right?)

So, I’m going through the lessons, and one of them – sorting the frequencies of inputted words by using a hash – plays pretty fast and loose with variables. Now, it’s made it clear that variables, at least when you’re slapping them between “| |” are just placeholders. I get that. The tricky thing was that, in this particular lesson, we’re forming a hash out of single keys. In this case, words inputted by a user. So, rather than a multidimensional array (i.e., the sort of thing that would require a key and a value in between the |s), we’re just dealing with single things.

Follow me? Hopefully.

Point is, as I’m going through this, I do what I think is correct, and keep being told that I’ve set the hash up incorrectly. Now, I know that’s not right. I know that because I’ve set the variable – “frequencies” – equal to Hash.new(0), just as it should be. So the hash is correct, damn it. And, as I am wont to do in certain situations, I try it a few more times, hoping that at some point, the machine will realize that it’s wrong and I am right.

Of course, that didn’t happen. What was happening, however, was a bit of miscommunication in the form of documentation. See, the author of the course obviously knows his Ruby. In trying to explain this course, however, he’d skipped over the fact that, when you’re sorting a hash, it becomes an array. (I.e., it assigns a value based on the frequency [in this case] of the appearance of a word. So, in this example, the word ‘the’ appeared twice. So, the multidimensional array became “the” => 2. Of course, this was all set up earlier by splitting up the individual words in the input by way of “words = text.split” and then slapping a method to “words” so that the program tallied every appearance of a word. Anyway.)

So, if I haven’t lost you there (WordPress really needs a footnote function), then what we’re at now is that I’m looking at what is clearly a hash, being told that there is no hash, and then being confused. So, after bashing my face against the metaphorical wall a few times, I went to the Q&A forums, where one guy helpfully suggested thinking of the variables as:

|words, frequency|

instead of

|a, b|

as had been displayed in the lesson.

Perhaps you’re thinking, “Well duh. What else would it be?”

Well, for me, who’s still on his first cup of coffee, trying to remember if any of this was covered in my Ruby on Rails course (it was – just very briefly and in one of those “You won’t have to remember this for the test” ways), that made all the difference.

And, further, it made me realize just how important documentation is. It’s so, so important to remember that other people may be looking at your code, so you have to make sure it’s not in your own bizarre mind-language, whatever that may be. And I also think this goes double for editing manuscripts – moreso when you’re doing it by hand. Really, anything where you’re working with other people.

Documentation: Make it like breathing.