The Importance of Documentation

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.

Advertisements

Area Man Amazed by Prevalence of Popular Music

PORTLAND, OR – Aaron Simon, a new arrival to the city, is reportedly amazed by the prevalence of popular new-folk band Mumford & Sons, sources claim.

“They’re everywhere,” the man has been heard to say. “It’s like they’ve had two very successful albums, or something.”

The band’s first album, Sigh No More, which reached No. 2 in the U.S. Billboard charts and was honored as the best album of 2011by the BRIT Awards, is a popular fixture in independently-owned coffee houses in the Portland area. The singles “Little Lion Man” and “The Cave” remain popular fixtures of alternative radio stations.

“They’re songs that keep people happy,” said Adam Leverde, owner of The Eightfold Path, a North Tabor coffee house. “Whenever I’m in control of the music, I try to play some Mumford once or twice. Customers really like ’em, you know?”

The band’s songs involve traditional folk rhythms and, often, spiritually- and literature-inspired lyrics.

“Wherever I go, man,” said Simon. “It’s like it’s all people want to hear. It’s like these songs really resonate with people.” The area man then pointedly sighed.

The band could not be reached for comment.