Vincent Gable’s Blog

May 24, 2010

Never Name a Variable “Index”

Filed under: Bug Bite,C++,Cocoa,Objective-C,Programming | ,
― Vincent Gable on May 24, 2010

Never name a variable index, especially in C.

Instead say what it indexes. For example, if it is used to index an array of Foo objects, call it fooArrayIndex, or currentFooIndex.

If the index variable is just used to enumerate over a collection of objects, (eg. for(int i = 0; i < arraySize; i++){…} ) then iterate smarter, using a simpler construct that doesn’t require declaring auxiliary variables. (Eg., in Objective-C use Fast Enumeration). It’s not always possible to do this, but it’s always a good idea to try.1

Why index is Especially Bad in C

The standard strings.h header declares a function named index, that finds the first occurrence of a charicter in a C-string. In practical terms every C program will have the index function declared everywhere.

But when a variable is declared with the name index it shadows the function — meaning the local variable named index takes over the name index, so the function can’t be called anymore:

char * world = index("Hello, World", 'W');
NSLog(@"'%s'", world);

Prints “‘World'”, but

int index = 0;
char * world = index("Hello, World", 'W');
NSLog(@"'%s'", world);

Won’t compile, because an int isn’t a function.

Obviously this is a problem for code that uses the index() function — but honestly modern code probably uses a safer, unicode-aware string parsing function instead. What’s given me the most trouble is that shadowing index makes the compiler give lots of bogus warnings, if you have the useful GCC_WARN_SHADOW warning turned on.

There are other good reasons as, specific to Objective-C, which Peter Hosey covers.

1If you really can’t think of a better name than “index”, I prefer the more terse i. It sucks, but at least it’s shorter. Brevity is a virtue.

July 19, 2009

For iPhone and or iPod Touch and or Other Things As Well

Filed under: Announcement,iPhone,MacOSX | , , , , , ,
― Vincent Gable on July 19, 2009

It’s very clear that a program “for Mac OS X” works with any personal computer Apple sells, because they all have “Mac” in their name. Unfortunately, the flavor of OS X that runs on the iPhone and iPod Touch is officially called “iPhone OS” by Apple, which it implies an incompatibility with the iPod Touch, and any future device that doesn’t have “phone” in the name.

I don’t know a good way to unambiguously say that a program is for any iPhone OS device, without tedious enumeration.

“For iPhone OS” sounds like it excludes the iPod Touch.

“For all models of iPhone and iPod Touch” sounds terrible. It will sound even worse when Apple comes out with other iPhone OS devices (“…for iPhone or iPod Touch or iTablet or iFPGA…”).

Apple could help by renaming “iPhone OS” to “Mobile OS X”, but I don’t see this happening.

I personally lean towards using “for iPhone” in general writing, and clarifying, if necessary, in “systems requirements” fine print. This feels closest to how the press covers iPhone OS applications, and of course it’s how Apple named the OS.

I’d love to hear what you call iPhone OS applications, and why.

May 6, 2009

No Common Name

Filed under: Quotes | , , , ,
― Vincent Gable on May 6, 2009

The problem with insects is their sheer number. There are millions of species. How many million we can’t say, and our guesses even as to the appropriate order of magnitude are tentative.* Certainly, there are too many for any language to absorb into common parlance. Most pass their lives entirely unnoticed by humans, and any specialists who happen to work on them are content with the scientific names. This is to say, most insects have no common name at all.

*for more on the diversity of life, see Rob Dunn’s book Every Living Thing.

—Alex Wild

January 7, 2009

Objective-C 1.0 Style: Don’t Name Your Enumerators “enumerator”!

Filed under: Bug Bite,C++,Cocoa,Design,Objective-C,Programming,Tips,Usability | , , ,
― Vincent Gable on January 7, 2009

Disclaimer

There is a better way to iterate over collections in Objective-C 1.0. You really should use it. It’s easier to write, easier to read, less prone to bugs, faster, and makes what I’m going to rant about here a non-issue, because you won’t have any NSEnumerator variables in your code.

Badly Named Problem

The standard iteration idiom in Objective-C 1.0 is:

NSEnumerator *enumerator = [collection objectEnumerator];
id element = nil;
while( nil != (element = [enumerator nextObject]) ) {
   ;//do stuff...
}

Unfortunately, I see otherwise steller programmers name their NSEnumerator variables “enumerator”. That’s always wrong, because it does not tell you what the enumerator enumerates. We already know that enumerator enumerates things, because it’s type is NSEnumerator, unless it’s name tells us more then that it’s hardly better then no name at all.

This is an especially amateurish practice because …

Naming an Enumerator Well is Easy!

Call it, the plural of the element variable. And if that won’t work you can always fall back on calling it collectionEnumerator.

For example, to fix:

NSEnumerator *enumerator = [input objectEnumerator];
NSString *path = nil;
while (path = [enumerator nextObject])

We should name enumerator paths or inputEnumerator. You might find “paths” to be too close to “path” in which case let the “plural form” of element be everyElement, giving everyPath.

These rules can be applied without much thought, but will improve the clarity of code.

Why enumerator is Worse Than i

Firstly, the practice of naming an the index in a for-loop i is not good. You can avoid it by renaming i to thingThatIsIndexedIndex.

But at least, for(int i = 0; i < collection.size(); i++), is concise; therefore better than a equally-poorly-named NSEnumerator.

Also, there is something to be said for the idiom you can just use collection[i] over declaring an extra element variable.

The Right Choice

Everyone agrees informative names are good, yet poorly named enumerators are everywhere (just browse Apple’s sample code!) Poorly named enumerators persist because nobody really uses an enumerator per se, they are just part of an iteration idiom. (So stop declaring them and iterate smarter). When was the last time you saw code that did anything with an enumerator besides [enumerator nextObject] in a while loop?

But bad habits matter. Don’t pick up the habit of naming something poorly when it’s easy to do the right thing.

Powered by WordPress