Adam @ Bitscribe

I get bored easily. As such, I always want to move around to different projects to keep myself challenged, break up the routine, and get fresh perspectives. Luckily my current line of work, consulting, gives plenty of opportunity for this sort of intellectual wanderlust.

One surprising side-effect of my thirst for new projects is that it seems to result in higher quality output, especially in terms of code maintainability. I’m going to call this effect cross pollination. By moving developers around within the team to work on different components, no area of the code becomes the exclusive domain of just one person. This in turn results in healthier code, because different people are examining and trying to understand any given module. They ask questions like “Why does this bit of code work this way?” - a question very rarely asked of code one is familiar with.

If something is hard to understand or change right now, it’s probably going to be fragile over the long run. (It’s like the old technique for programmer job security: “If it was hard to write, it should be hard to understand and even harder to modify.”)

This article advocates a common approach to this problem: get programmers to train other programmers on the quirks of the codebase. I see this is little more than a bandaid. The real solution here is not to let software turn into quirky, only-one-or-two-people-know-how-it-works code. Cross-pollination of developers ensures that people are always writing code that is understandable to any other developer. The important thing is not having a certain number of developers that know the code, it’s making sure that you’re getting new eyes on the code from time to time.

A truly well-written piece of software can be easily understood and modified by any component developer familiar with the underlying tools. They need not “know” the code. Reading it - and especially reviewing the unit tests - will give them all the information needed to fix bugs or add features.

Mark-Jason Dominus’ Why I Hate Advocacy draws attention to common fallacies made when arguing for any particular tool or method. He makes many excellent points, but my favorite part was this hilarious quote:

“Perl’s motto is “There’s More Than One Way To Do It”, and sometimes that means that one of the ways is to use PHP.”

I’ve been using TextMate on my Mac for a while now, trying to train myself back into using (gasp!) the arrow keys for navigating a text document. After a decade of using the mighty vim to edit source, emails, and all other manner of text, it’s not easy to make the transition, even though TextMate is very easy to use and learn.

Ultimately TextMate is not as powerful for editing text as vim - nothing is, except probably emacs. But vim is a very focused piece of software (in the fine UNIX tradition of small, sharp tools). It absolutely cannot be beat for actually editing text, especially code. But for anything beyond that scope, forget it. For example, something as simple as search-and-replace through multiple files is not included. Programmers used to development in IDEs would probably be shocked at this apparent omission.

So TextMate can’t compete on editing text, but it makes up the difference elsewhere, by providing a broader set of tools. The most immediately useful feature I’ve discovered is Apple-T, which allows you to open a file anywhere in your project tree by typing an abbreviation, learned by the editor based on your historic habits. For projects with many files and especially a multi-level directory hierarchy, this is a much faster method of getting to individual files, especially those you access frequently, than traditional approaches.

But using it has left me feeling that this is only the tip of the iceberg: editors could go much further with the same idea. For example, in the Rails directory layout, you have many files named index.rhtml. Each is in a subdirectory named for its component, e.g. views/account/index.rhtml or views/product/index.rhtml. But TextMate searches on the filename only, not the directory, so you’re reduced to using the arrow keys to scroll through the list of index.rhtml entries.

Why go by filename at all? Who really cares what source file our code resides in? Instead we should be thinking in class / object space. I want to go to Account::sendOverdueNotice(). Figuring out that that resides in classes/account.php, opening that file, and then searching for or scrolling to the method definition is a very indirect method of navigation. Extending the TextMate approach, this would work something like hitting Apple-T and then typing “acct:sendover”.

The astute reader might point out that ctags, a fairly standard UNIX tool, has offered something like this for decades. With a modern version like Exuberant Ctags (on Ubuntu: apt-get install exuberant-ctags), type “ctags `find . -name *.rb`” in the top level of your Rails project. Then you can use a command like “vi -t send_overdue_notice” at the shell prompt, or “:tag send_overdue_notice” from within vim to jump straight to that method. (The latter offers tab completion, which is very nice, though not quite as nifty as the TextMate abbreviation thing.)

Ctags covers about 75% of what I’m suggesting. But it hasn’t changed much in recent years, and that last 25% is pretty crucial for this to really be a pleasure to use. In some ways ctags is worse for the wear today, because (as near as I can tell) it doesn’t support any object space mapping. If you have two identically named methods on different classes you can’t access more than one. You also have to regenerate the file periodically by hand… which could be automated with a cron job, but long story short is that I’ve never found myself using ctags long-term, despite the incredible potential it promises.

Take my idea above and put it in a nice friendly editor like TextMate, along with the niceties that you’d expect from such an app, like automatically generating the index, mapping the class space as well as method names, and autolearning abbreviations. Then allow the user to use this same interface to create a new method. i.e. if you try to jump to one that doesn’t exist, it starts you on a blank slate in the right place.

With an interface like this, you won’t even care how your files are stored. They could be all in one giant directory, or spread out across a tree like Rails, or whatever. The editor would decide that according to some sort of basic criteria for the language, defined by some sort of internal scripting, similar to how syntax highlighting is handled.

Furthermore you won’t care about the layout within the file. Historically I’ve spent a lot of time worrying about how the methods should be ordered. This is not something that can be solved satisfactorily for any decently large object. Method interactions are in a web, two-dimensional at least, perhaps more. Files are one-dimensional, so trying to group like methods in a logical order is a pointless and frustrating exercise. Eventually I gave up on worrying about this much, but I wonder how many other coders waste brain cycles on this without even realizing that they are doing so.

What’s more, your editor should behave sort of like a web browser: every method call is a hyperlink (activated by the keyboard, of course) to its class definition. I realize that many IDEs have something like this already, but it never feels like a first-class citizen in the navigation tool family, more of a tack-on feature. Done right, and in concert with the class/method name abbreviation jump, I think that developers could be way more efficient in our day-to-day work of navigating source code.