The Importance of Documentation


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:


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, 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.

Adventures in Coding, Pt. 2

My last post about my coding adventures was destroyed by my negligence. Let’s hope this doesn’t suffer the same fate.

So last night, since I was able to work on the computer without a stormborn power outage, I fired up the second lesson of my Ruby on Rails class. The first lesson was centered around generating a new app, which led into a breakdown of all the bits and bobs of Ruby – gems, gemfile, some brief examples of code, all that stuff – as well as the essentials of uploading app frameworks to GitHub and Heroku.

The second one is building pages.

HTML and CSS, as I was telling someone, rely a lot on creating pages and stylesheets as if they are each different documents. Essentially, that doesn’t change with Ruby, but Ruby makes it a lot more convenient – and fast, I think. Whereas in HTML and CSS, I’d find myself opening a new document in Sublime Text, then editing it through that, and saving it as either .html or .css, Ruby has a command:

[current directory] $user generate controller Pages [name of page]

So, typing that into Terminal gives you a shiny, new, blank html page to work with. After editing the pages controller file in the database – changing definitions and actions so the app directs to the correct pages – you can have a url point to “home” rather than “home.html”.

This makes me grin. I don’t know why – exactly – but I had wondered why some pages allow that to work without a file extension, whereas others don’t. And it’s all through the power of Ruby. [Collective “Ooooh” and “aaaaah”]

Further, all the messing around with copying and pasting navigation bars, logos – well, everything that’s not the page-specific content, really – can be accessed using partials. Partials are bits of code that look like:

<%= render ‘[containing folder/filename (i.e. ‘header’)]’ %>

What that’s doing is telling the page to render a certain bit of code at a certain location, and spit that out on a page. You do that by putting the above code on a layout page, which controls the default view of every page.

Everything that’s not defaulted into a page is plopped into that layout by

<%= yield %>

From what I saw last night, that looks like it’s included by default when you generate a new page controller. But if you’re reading this, and you know that’s wrong. Let me know!

So, basically, all you have to do when you generate a new page is write in the HTML for the content of the page.

My God, it’s so easy!

(That said, I think I’ll still keep using <a href=”…”></a> for links. <%= link_to ‘…’ ‘…’> just feels wrong.)

Of course, there are the details to work out, like defining the pages and controllers, and all of that, but man. I get why people scoff at Ruby, but it seems like doing so would be like looking down on people for driving a car when they could be riding a horse. (Or flying across the country when they could be driving…)

So excited, you guys! Just wish I could rewatch these videos to hammer in the ideas, but nooOOoOOooOOooOOo. I should be working. Thanks, The Man.