mtrpcic.net Writing software since 1932

Documentation – The Nectar of the Gods

Since day one of college, documentation was toted as being of the utmost importance.  It was necessary, at all times and in every situation.  "By god, what does the variable "i" mean in this "for" loop!?" I could imagine my professors mumbling as they read through my code.  Of course, when I was writing that code, it was painfully obvious what "i" was doing.  It's always obvious what "i" is doing - isn't it?

Of course, my example above is a bit simplified, but it proves the point none the same.  No matter how complex the code that you're currently working on may seem, it's always within the realm of understandability.  Step back for several weeks, and walk into the hellish nightmare that is The Spaghetti Abyss, and you'll spend five minutes wondering, "What the hell was this fool doing?" followed by a brief flash of recollection and embarrassment - "Gasp! I am that fool!"

And therein lies the rub.

As soon as I finished my time in school, documentation seemed much less important.  You see, up until this point, students had been documenting merely to get the marks for it.  We documented our code because our grades depended on it.  As soon as I stepped out those doors for the final time, I remember thinking I was free of that nightmare.  I was a good programmer, I could look at code and understand what was happening under the hood; I didn't need an explanation.

Fast forward a couple of months, and I'm at work, trying to solve a particularly bad problem - a problem I inadvertently produced several weeks back, in a module that had since been left to stew in the bowels of a great beast of a project so terrifying, so insidious, it was Beelzebub incarnate (in code).  I open that file, thinking "This will be an easy fix - after all, I wrote it."  Never have I been more wrong in my life.  My undocumented code put a bucket over my head and slammed it with a baseball bat.  It took me several days to fix a bug that was incredibly simple, but my lack of documentation fanned the flames until my ego was burned to the ground.  I wasn't a good programmer anymore; a good programmer wouldn't have run into this problem.

Fast forward yet again.  I need to delve deep within the source code of ActiveSupport.  I'm looking at code written by the deities of code.  These men and women know Ruby from top to bottom, inside out, and to a peasant like me, it looked like they were making use of every trick in the book to get things done.  But, if that was the case, why was it so easy for me to understand everything?  Why was I able to follow along at a nice leasurely pace, instead of having my eyes melt off my face? Oh, I see now...

This code had documentation.  This code had a dictionary beside it, and I could find out what everything was doing every step of the way.  This code was easy.

It takes a situation like the one described above to let you know how important something really is.  You can be an amazing problem solver, and a prolific programmer, but you won't ever be considered one of the best until your code can be understood by thousands of people at a glance.  Now that I've got my own projects, I make sure that I do my best to document every code change.  I try to act like one of the best, because I'd like to be one of the best.

Accents are a funny thing.

Accents are a funny thing, eh?  Being a native Canadian, I'm constantly told that I sound Canadian.  I guess that makes sense, the same way that someone can sound Texan, or someone can sound British, Irish, or Scottish.  They're all speaking English, but there's definitely something different about each and every one of them.  Whenever you speak, you don't just speak in a particular language, you most certainly have a particular accent.

This got me thinking - When I program in a particular programming language, do I also program in a particular accent? Of course I do.

There are a thousand little things we all do when programming that individually have their own names (Naming Conventions, Indentation Style, Equality Checks, etc), but when you think of them as one combined unit, they construct your individual accent.

Naming Convention

There are so many different possible naming conventions that it's nearly impossible to guarantee that a large development team will all use the same ones in the same situations:

var userName = "Mike"; // Camelcase
var UserName = "Mike" // Upper Camelcase
var strName = "Mike"; // Hungarian Notation
var user_name = "Mike"; // "Ruby" Notation
// And many, many more.

Which conventions do you use in what situations?  Do you name Modules different than Classes?  Classes different than Methods?  Methods different than variables?

Indentation Style

// Do you like to keep your braces on their own line?
function totallyBananas()
{
    alert("Bananas!");
}

// Or with method/class definitions?
function totallyBananas(){
    alert("Bananas");
}

Do your conventions differ for method definitions, class definitions, if/else statements, or other code blocks?  Do you prefer 2, 4, 6, or 8 space indents for different pieces of code?

Equality Checks

// Do you like to check that things are equal?

if(authorized == true){
    alert("Hello, Mike.");
}

// Or inequality?
if(authorized != false){
    alert("Hello, Mike.");
}

Value-First Comparison

We most often see the variable name come first when doing a comparison, but this can lead to some embarrassing mistakes...

var name = "Mike";
// We've all seen this before.
if(name == "Dave"){
    alert(name); // You should never see this!
}

// But this isn't what we meant!
if(name = "Mike"){
    alert(name); // You're going to see "Mike"!
}

Some people have taken to doing "value first" comparisons, which can avoid these mistakes.  Which way do you speak?

if("Mike" == name){
     alert(name); // You should never see this!
}

// This will throw an error.
if("Mike" = name){
    alert(name);
}

There are hundreds of other little things that make up your "programming voice".  Your documentation style, namespacing habits, source file naming conventions, and even your SCM commit messages are all little pieces of what your code sounds like.  So, is your code from the royal palace, or the Louisiana swamps?  Regardless of what your code sounds like, just make sure that your coworkers and colleagues can understand your accent.

The fine line between “Code” and “Good Code”

I've been spending a fair bit of my spare time working on my current project, and one of the major issues I'm having right now is drawing the fine line between writing code, and writing good code.

How many times have you sat down with a good, solid idea, only to sit and stare at your monitor for 30 minutes because you're trying to think of 30 different ways to accomplish the same goal. You end up asking yourself 10 different questions, each with 10 pros and 10 cons, and you wind up with a very solid understanding of what the end product will do, but you've made no progress towards it.

"Is this going to be DRY enough?"

"Should I use List Comprehensions here?"

"Should these be params to the method, or passed in when the object is initialized?"

I find myself running into this problem quite often, and always come to the same conclusion.  The conclusion that should be at the heart of as much as your logic as possible; Keep it simple, stupid.

When you're confronted with the "Mile-a-Minute Mind" scenario, just sit back and write whatever code comes to mind that gets the job done.  You're not writing good code, you're just writing code. Wow, that was easy?  It's ugly, but it was easy.  Alright, what's next?  Well, you could (and should) write any pertinent Unit Tests for the code you just wrote.  Make them as solid as you can.  Now you've got a product.

Congratulations, you fought through your own indecision, and wrote some code.

Now we're excited.  What next!?  Well, you wrote some code, and you wrote tests for your code.  Now comes the fun part.  Now you can get rid of that code, and replace it with what we've wanted all along; good code.  Thanks to our wonderful Unit Tests, you'll know if your new code is up to the same dastardly deeds as your old code.  Refactor your work of art to your hearts content, until it's as good as it can possibly be.

The moral of the story is that indecision is the bane of productivity.  Don't worry about writing concise code.  Don't worry about writing optimized code.  Just worry about writing working code, then take it from there.  As we say in the world of Test Driven Development, "Red, Green, Refactor."