Computing for Everyone 4: Clarity

Last time we looked at some basic JavaScript code to start learning how to read and write source code in general. Before continuing, I'd like to show you something about writing code.

Here's that first bit of JavaScript I wrote for you:

function greet (visitor) {
  var greeting = "Hello, " + visitor + "!";
  return greeting;
}

Armed with your basic knowledge of how JavaScript works, it's pretty easy to tell what this code is trying to do.

What if I wrote it this way?

function g (v) {
  var h = "Hello, " + v + "!";
  return h;
}

Functions g and greet behave identically, but notice how greet names what my function does much more descriptively than does g, and visitor and greeting describes the data I'm storing in my variables much better than v and h. If the two functions behave identically, why did I choose to write the longer version? Because when you write software, you aren't only writing the software in a way the computer can understand it; you're writing it in a way that you can understand it.

Even when writing your code, you will spend most of your time trying to read and understand what's there. Writing software is a process of building with your mind. It's a process of learning, understanding, and describing in detail. Here are two more ways I could have written the function:

function doWhateverThisFunctionDoesWhoKnowsAnyway (santaClaus) {
  var hoHoHo = "Hello, " + santaClaus + "!";
  return hoHoHo;
}

These kitschy names obscure what the code is trying to do.

function xxxxxxxxxx (xxxxxxxxxxx) {
  var xxxxxxxxxxxxx = "Hello, " + xxxxxxxxxxx + "!";
  return xxxxxxxxxxxxx;
}

The different identifiers differ only in the number of x characters in their names. Oh, one more thing about JavaScript: statements are separated by curly braces ({}) and ; characters--we don't actually need any of those line breaks or most of those spaces. This is legal JavaScript:

function xxxxxxxxxx(xxxxxxxxxxx){var xxxxxxxxxxxxx="Hello, "+xxxxxxxxxxx+"!";return xxxxxxxxxxxxx;}

It's not enough to write programs that do what you want the first time: you have to avoid going crazy during the process. Your programs should not only do what you want when the computer reads them, but they should be understandable in intent and mechanism when a human reads them.You will thank yourself when you want to add something new to your program later and when you have to track down a mistake in your code.

Programming languages will let you freely choose names for your functions and variables. Your variable names should describe what they represent; your function names should describe what your functions do. Like so much else in life, clarity is your friend.

Exercise:
Go on a ~20-minute Wikipedia binge rooted at the article on the programming language named brainfuck. Make sure you hit the article on Turing tar-pits along the way. Also, there are contests for writing unintelligible code. To each his or her own.

Bonus:
If your life depended on it, how would you label your goblets to avoid confusion like that encountered by Danny Kaye in this scene from The Court Jester?

Quotes:

"Everything [in Digitopolis] is called exactly what it is. The triangles are called triangles, the circles are called circles, and even the same numbers have the same name. Why, can you imagine what would happen if we named all the twos Henry or George or Robert or John or lots of other things? You'd have to say Robert plus John equals four, and if the four's name were Albert, things would be hopeless." - The Phantom Tollbooth

"Everything should be as simple as possible, and no simpler." - Albert Einstein

"There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies." - 1980 Turing Award laureate Tony Hoare