Essays, washrooms and variables

I seem to be writing a lot more these days. As in longer in length. Such as the article on functional specs, the unhealthy focus on flaws, or the fear of authentication.

When I was younger, I hated writing stuff. I’m fairly fluent in English. I just hated the composition part. My mind was better at grasping at concepts, and using them in spurts. Making me write essays with a minimum length or number of words was torture. Geography and history were the bane of my studious years…

Mathematics suited me. Couple the conciseness of mathematical expression with elegant programming code, and here I am, a programmer. I’m actually surprised that I can write so much. I will vary the length of my articles more. Sometimes, short articles work just as well to bring my point across.

Anyway, I found someone who shares my opinion about talking in the toilet. See point number 2.

Then there’s the advice on keeping variable naming simple for purposes of competitions or tests. Because

the lifespan of the code is 30 minutes, not years or decades

Contrast that with variable naming for clarity, for easy maintenance, and for the sanity of your fellow programmers.

Why you need linguistic skills – part 1

Language in dictionary by Christian Grass @iStockphoto

While writing code may seem very logic-based and technical in nature, your skill in human languages is equally important. Why else would Visual Basic read like English? In this series of articles, I’m going to talk about why improving your linguistic skills make you a better programmer.

Broaden your mind

A limited range of vocabulary restricts your imagination. Part of imagination requires you to describe something. The more words you can use for describing, the more vivid, the more exact and the more complete the object of description becomes.

As a programmer, you have to translate business logic, task requirements and given instructions into code. The better your grasp of language, the better you’re able to imagine the final product, and thus the better you’ll be able to visualise the code and write it. What it comes down to is you must understand something that someone else wrote. You need to know the nuances of your language of choice because that someone may have wanted one thing, but actually wrote something else.

For example, in one of my user task requests, there was this requirement about entering random input. Based on the business context and the web form that was to support this feature, I deciphered it as being able to enter any range and any number of input in a specific format. I checked with the user, and it was indeed that way. Sometimes users lie, unwittingly perhaps, and in this case, using the wrong words to describe what he wanted.

Give it a name

What’s the one thing you do every time you code that requires linguistic skills? Name your variables. Every time you declare a variable, you make a conscious choice on what that variable’s fate in the ensuing code is. Every time you name a variable, you make a conscious choice on what is required of the variable.

There’s a concept I read in a fantasy story by David Eddings, and it goes like

Know the name of an object, and you gain power over the object

Yet some programmers are lousy at naming variables. Some programmers don’t care about the variable names. I bet some programmers even hate naming variables. Why else would there be names such as “a”, “b”, “c”, “DataGrid1”, “DataGrid2” and “Table1”?

Of course, there are perfectly rational decisions on using certain names. Variables in loops are usually single letters, and they are usually “i”, “j” and “k”. That’s probably a 3-level nested for loop in the making. I’ve gone up to “l”, “m” and even “n” before (matrix manipulations. Fun).

Based on context, you can easily know what those loop variables are used for. And that’s the important point, the context in which a variable is used. A simple “dt” for manipulating dates and times in a small and well-defined section of code is ok. But if there’s no context, can you tell what the variable is used for?

“It’s compiled into an executable anyway. Besides, there’s the search function,” you say.

Of course, tools such as Lutz Roeder’s Reflector make it easy to obtain code. You can use the search function to find where a variable is used and thus gain an understanding of its purpose. “t1″s and “t2″s don’t bother you at all.

Writing code is in the same spirit as writing a sestina, or writing a letter, or writing a business document. You are writing to be understood. And until artificial intelligence improves, you’re writing to be understood by a human.

The compiler might understand what you wrote (or not, depending on how bad a programmer you are). But you’re really writing for a human being. Someone is going to use that application you wrote, and they’d better know what it does. Someone is going to maintain your code, and they’d better understand what it does.

I can understand the difficulty faced by my Chinese reports (stationed in China), whom I pass some programming tasks. English isn’t their native tongue. The specification documents need to be written in easy, simple language for them to understand the business logic. Before any French or German programmers hammer me with protests, I want to point out the importance of the language used in the communication. Again, it’s about context. If your users use English and your documents are in English, your code had better be easily read in English.

Obfuscated code is hard to read because the context is taken out, be it requirements, indentation, spacing or addition of superfluous stuff. To add and support context around code, you need a certain level of linguistic proficiency (yes, basic spelling and grammar counts).

So my conclusion with bad variable names is that they arise out of a combination of:

  • Limited vocabulary range
  • Lack of imagination
  • Plain laziness

What’s your excuse for bad variable naming?