, , ,

When you write code, always remember Rule #2: Source code is for humans. This rule ties to Rule #1 about clarity. You’re writing for humans, so write clearly! The compiler can understand any syntactically correct ball of mud you make, but humans need all the help you can give them. Write for your human readers, not the compiler.

The order of things is one way you make source code clear. How you order your functions or methods can help communicate your intentions to a reader. (I’ll talk more about code organization in the future.) Good comments, of course, are crucial. There are many important ways to write clear code.

The names of your variables go a long way in communicating your intent. The compiler couldn’t care less, but a longer, descriptive name can be a blessing for a human reader. Don’t be afraid to use descriptive variables names. The days of compiler length restrictions are safely behind us, and editing environments help remember and type names for us. Besides, programmers should be good typists, right?

At the same time, don’t go nuts. Verbosely long names can make the code look cluttered and ungainly. You want some degree of streamlining; that’s a part of clarity, too. (The yardstick to use is always: How will this look to someone reading this for the first time?)

One thing about variable names is that you want a naming convention. You want a way of going about the business of variable names that gives you the same name in the same situation.

[After years of doing this, I sometimes surprise myself by how well variable names match across a project. Sometimes on a large project I’ll start to create a new class and then realize something like it already exists in the project or in a library. If it’s one I made in the last few years, chances are the one I just started looks surprisingly the same. Source code is one place where you want to be predictable. You want some moves to be instinctive.]

One example is that my loop indexes are always ix.

The “i” changes to other letters, but the two-letter name ending in “x” is a standard I use faithfully. For nested loops, I’ll use ix then jx then kx. If necessary, I’ll use mx and nx if I actually have to iterate over something with five levels. I skip lx because the “l” (el) looks so much like a “1” (one).

If I were iterating over a matrix, I might use rx and cx for row and column.

I knew a programmer who used ii and jj and so forth. When I asked him about it, he said it made searching for index variables easier. Source code could easily contain the bare character “i” in comments. In general, searching for single characters can be problematic, so his solution was a good one.

I adopted it and changed it to use “x” as the second character. It represents the last character in “index“.  In fact, the entire variable, ix, represents “index” via a common abbreviation technique: first and last letters.

It often doesn’t matter exactly what technique you use. Find one that works for you. (Some coders may be required to follow company guidelines. To the extent possible, it’s still good to develop your style and approach.) One key is consistency. The more consistent you are, the less likely you will make errors. It’s about good habits!

Next time I’ll talk a bit more about naming conventions.