How Method Names Can Bite You ...

As a professional programmer, it often happens that you create a program, then don't hear from the client for half a year or more, and then the client asks you to return to that project and make some small changes. If your memory isn't excessively good, or you haven't had any other jobs in the meantime, chances are you'll have no idea what the project was about back then. You have a vague impression, but you don't remember the details.

Whether it's the problem of finding the correct files on a client's server where many of your predecessors left their traces, or whether it's a program you wrote all by yourself but which is more on the complex side doesn't really matter. This is exactly the case where you'll be thankful if you wrote some sensible comments in your code. However, sometimes not even those help. A sensible and disciplined naming scheme for methods, constants and classes can go a long way to help.

For example, a while ago, I made some improvements to UKDistributedView, which included a cached list of all visible items. This speeds up drawing significantly for lists of a couple thousand items, and on a click you don't have to loop over all items, just the visible ones. The main method to rebuild this cache was named cacheVisibleItemIndexesInRect:startingAtIndex:. Now, that sounds perfectly fine, until you realise that this actually doesn't recache. It only adds to the cache. In all old cases, I was calling invalidateVisibleItemsCache before this, but in one particular case I'd written later, I'd assumed that would happen automatically.

What resulted was that items were duplicated in the visible items list. Worse, the problem didn't really show up until there were more items than would fit in a scroll view (because otherwise an optimisation would bypass that code path). The only thing I saw was that certain items' alpha shadows were drawn black, as if they had been drawn a dozen times over. Which they had.

Lesson learned: I renamed cacheVisibleItemIndexesInRect:startingAtIndex: to extendCacheByVisibleItemIndexesInRect:startingAtIndex: and added a comment reminding future Ulis (i.e. me in another year) to call invalidateVisibleItemsCache before this. The reason this is a two-step process is that I have cases where I only want to add to the cache, and then it saves a lot of time not having to redo the old items.

That's what self-documenting code is all about.

Reader Comments: (RSS Feed)

No comments yet

Or E-Mail Uli privately.