The Mindset

Over the years I have seen numerous variations of code naming conventions. I have also heard a similar number of debates on which notation is better. In most of these discussions no one bothered to define what it should be better for.

In this post I am not going to get myself involved in this futile war. I do wish however to introduce a different perspective on the topic which I believe is often ignored: the ergonomic perspective.

Programming is Different From Writing

Physically, that is. The mechanics of writing code is different from the mechanics of writing plain English. The most noticeable difference is in the usage of different characters and capital letters.

In a common English sentence (like the one you are reading now) you have one or two capital letters. A simple word processor will even spare you the need to capitalize the first letter in the sentence. And most English sentences do not contain special characters such as _, & and *.

Let’s do a little experiment. Open your favorite text editor and type the first paragraph of this post. Now, do the same but make sure to capitalize the first letter of every word. Finally, type the paragraph again, but this time use an underscore character instead of spaces.

Now, I am not an ergonomics expert, but I believe you will find the first version the easiest to type. Reaching for the Shift key for every word you type (either for capitalization or for inserting an underscore character) is not natural. When done excessively it probably isn’t too healthy either.

But when we write code, we do just that. We use many special (and hard to reach) characters, and almost every other word starts with a capital letter (or separated using an underscore character).

At the same time, there seems to be no other option for programming. Clearly, we cannot use spaces to separate words in entity names. Maybe this is the reason that many developers use cryptic and short names instead of meaningful ones. But this is not acceptable either. For code to be usable for the developers who work with it, it has to use meaningful names for classes, methods, and variables.

Separation of Concerns

The solution to this problem is separation of concerns. We have two separate problems: making code easier to write and making it easier to read. The fact that both problems deal with the same artifact does not force us to use the same solution.

Let’s start with reading: for code to be readable and easy to understand, you should use meaningful names. Writing short and cryptic names is unacceptable. Writing names without separating words in any way (somethinglikethat) is of course not acceptable either.

So, in order to make your code readable, use a reader-friendly notation for entity names: Either ThisOne or that_one. Both seem reasonable, but do your best to meet the expectations of your target audience.

Now for the writing part, which is where we started. With the help of various tools you can make the code writing task more writer-friendly.

Warning: this part is not for VI fans:

IDEs, editors and plugins which offer IntelliSense, AutoComplete, or any other feature in this family are great for making the code-writing task easier. Many of the entity names you use when writing code can be accessed with just a couple of keystrokes.

Another idea is to use a tool that enables you to write case-insensitive code and corrects it as you type. Most of us don’t use the same name twice with different capitalization. So, every tool that maintains a symbol database in your development environment can auto-correct the names you type. You will type getname and it will change it to getName. I never saw such a tool that does that automatically for every symbol you type, but I would be happy to be wrong on that one.

In short: do whatever you can to make your life easier when writing code, but don’t compromise the quality of your code in order to do so.

This entry was posted on Monday, June 12th, 2006 at 12:35 pm and is filed under Usability, Code Quality, Ergonomics. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.