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

17 thoughts on “The Importance of Documentation

  1. Hello There. I found your weblog the usage of msn. This is an extremely neatly written article.

    I will make sure to bookmark it and come back to read more of
    your useful info. Thank you for the post. I’ll definitely return.

  2. New varieties of custom-made styles can be formed with these magnificent accompanying items.
    No muss, no fuss, easy color stick in the palm of your hand for ease of application. There are hair coloring products out there that are truly all natural, safe and non-toxic.

  3. It’s a shame you don’t have a donate button! I’d without a
    doubt donate to this fantastic blog! I guess for
    now i’ll settle for book-marking and adding your RSS feed to my Google account.
    I look forward to fresh updates and will talk about
    this blog with my Facebook group. Talk soon!

  4. Hello There. I found your weblog the usage of msn. This is a very smartly written article.
    I’ll make sure to bookmark it and come back to read
    more of your useful info. Thank you for the post. I will definitely return.

  5. Pretty component of content. I just stumbled upon your weblog and in accession capital
    to claim that I get actually loved account your blog posts.

    Any way I’ll be subscribing on your feeds or even I success
    you get entry to persistently quickly.

  6. I was suggested this website through my cousin. I’m now not sure whether or not this publish is
    written through him as nobody else realize such specified approximately my problem.

    You’re incredible! Thanks!

  7. It’s nearly impossible to find educated people in this particular subject, however,
    you sound like you know what you’re talking about!
    Thanks

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s