Briefing #FR970616-2

Writing Lucid Code

Contributed by Jeff Gainer
Arrowhead Systems Consulting, Ltd.

What Does Montana Have to Do With Writing Lucid Code?

Several times a year, I pack a few pairs of Dockers, an extra pair of Topsiders, a huge cache of technical manuals, one impeccably tailored dark suit (just in case), a notebook PC, and head for the airport in Missoula, Montana.

For those not blessed with a proximity to Western Montana, Missoula is a self-consciously quirky university town boasting one of the few airports in the area. By choice I divide my time between Hamilton, about fifty miles to south, and a small but comfortable yacht anchored in Polson, on the Flathead Reservation, about fifty miles north. According to the maps and the GPS, Missoula is in the exact middle. Why would I leave such a place?

Simple: The majority of ASC's revenues come from large software centers, places like Minneapolis, Dallas, Charlotte and Boston. Montana is not a hotbed of software development, although we do consume large quantities of world-class latte. If I did nothing other than write exquisitely maintainable code, I could happily kiss my road warrior days good-bye and subsist here in my little office with PC and high-speed modem, or little boat with Pentium notebook and shore power. Code can be written anywhere. It does not require genesis in office cubes filled with empty Mountain Dew cans, pizza boxes and geeky camaraderie. I have demonstrated many times to clients that developers need not be always physically together, although I will concede the synergy of occasional in-person brainstorming sessions cannot be replaced (yet) by teleconferencing and ISDN lines.

More often than not, I find my role at a client site as less a project manager or team leader, but as a mentor, a coach. Entering my tenth year in the development field, I am still amazed and horrified by the number of trained, experienced developers unable to write simple, lucid code.

We've all been there, though, cleaning up somebody else's mess. Usually it is a spreadsheet created by a former employee who figured out how to do some moderately cool things with Lotus/Excel macros and then, an internal application, well, shall we say--evolved. I've cleaned up a half-dozen of those and turned down lucrative contracts to reengineer others. So much for experiencing complexity.

Worse yet can be the ill-conceived project written in a visual development environment--not by an inexperienced developer, but all too often, an experienced one. For years, everyone has groused about the fallibility of line-oriented BASIC: That it encourages spaghetti code. Muddled code. Unmaintainable code.

But visual development tools are not in themselves liberators--the very nature of visual development and event-driven programming makes it easier than ever to write more muddled, more unmaintainable code.

Case Study One

A few years ago, as a programmer--not senior developer or a technical leader--just another programmer on a small team rewriting a work of unsupervised development, I spent most of an afternoon trying to track down something called iDate in a huge platter of spaghetti Visual Basic code. Eventually I discovered that iDate was in fact a global string, but it had also been used variously through the program as a local variable of different data types elsewhere in the program. Obviously bad coding practice, but a little documentation in the code would have helped.

Later that day, I quietly suggested that we preface each module by a simple paragraph, explaining the principle of the module's purpose. It would help in maintaining the code, I explained, and more importantly, help us weed out the 30,000+ lines of superfluous code. An excellent idea, the team leader agreed, we would adopt it immediately.

"You know," he went on, "you're the only developer I've ever know who actually does that. I know everybody says to do it, but you're the only person I've ever met who does."

I was flattered but more than a little shocked--after all, this man had been in the software development business when I was in junior high. For the record, though, our team leader was being kind, as he always wrote lucid, well-commented code that served as an example to the rest of us.

Case Study Two

One of my stranger professional experiences was being called to Siberia (in the winter) for a post mortem, as it were, of a robotics system and its PC control interface. By this time, the project was in deep trouble, late and hemorrhaging money. My role was to slow or stop the bleeding, if possible.

The robotics code was in assembler and absolutely incomprehensible. There was no notation. Not a word. Worse yet, the original programmer was ill and a substitute had to work absurd hours just to begin to understand the code. The PC code, however, was a true joy. The developer had included extensive notation in French and English. Variables and procedures were clearly typed and named.

Incidentally, we were truly an international team: French, American, Canadian, Russian. While vainly trying to remember how to speak French, I taught my interpreter a few words in Cherokee, he taught me a whole bunch of words in Russian. We interpreted for each other in a round-robin fashion, yet through our code, we communicated in Hungarian.

Case Study Three

I had been retained by a company to provide them with some long-term direction toward reengineering their IS systems to a graphically-based client/server system. Among other things, I was to work with their internal staff, indoctrinating them into the strange new world of client/server, LANs, Intranets, code reuse, and event-driven programming.

I have been described as having an "evangelical personality". While in guru mode, I create and distribute the expected white papers of standards and guidelines. But I also distribute copies of useful articles, inspiring bits of distilled wisdom and pithy quotes. On a Thursday I gave everyone copies of Gen Kiyooka's Software Development article "Reusability is a Habit" (March 1994) followed by a Friday sermon on the same theme. On Saturday, I checked my email, and found that an attendee (or captive) of my Friday sermon had sent me the following:

"I have done it! I am a programmer reborn! This morning I had two requests for a similar function . . . and rather than create two functions, I took your advice to heart, wrote a single function with a parameter--and experienced the joy of reusability . . . . "

This young man went on to say that he had heard all this stuff in school, everybody said to do it, but nobody he knew every really did it.

Okay, so maybe there was a little parody in his reply, but his excitement was genuine. I replied with equal enthusiasm, and subsequently recommended to his management some sort of recognition, maybe a couple lunch vouchers at least. I don't know what ultimately happened to his career or compensation, but I can say that his professional life must be (provided that he continues and develops his reusability habit) increasingly less complex and more rewarding. More importantly, if he moves on to bigger and better things (and I believe he will) the code he leaves behind will be lucid and maintainable.

Just What Makes Lucid Code?

In all our requirements and specifications, we have the expected items--speed, functionality, ease of use, etc. But rarely is any attention given to the internal maintainability of the code. Maintainability, as mundane as it may seem, is simply producing easy to read, easy to understand, easy to maintain code. Sure, it's dull, but subsequent versions become easier, faster, and ultimately, better and more cost effective. Deadlines can be met, rather than having teams frantically patching around incomprehensible or undocumented modules, or spending precious weeks trying to comprehend the old version which might not be fixable anyway.

Just what makes lucid code?

Simple, clear notation. The explanatory paragraph at the top of the module. A module that does one thing, an one thing only. A module that can be used many, many times. Explicit declarations. Hungarian notation. Long, descriptive names.

i, j and k are no longer valid variable names. Module1 is not a valid procedure name. ssCombo1 is not a valid control name. Every time I look in technical manual and see these in examples I want to run screaming from the room.

sClientLastName and giInvoiceKey are valid, easily understood variable names. objCashDividends is a valid object name. gcllControlButtons is a valid collection name. With common sense conventions like these, the purpose of objGenericObjectPlaceholder should be pretty obvious. I live in terror of a junior team member asking me for help debugging code with names like: i, j, and k, or worse yet, something called Customer. Is it a text box, a command button, a data object, a string, integer or variant?

How can your organization ensure lucid, maintainable code? The solution is simple, but requires commitment and attention: composition and publication of a concise, comprehensive guide to internal development standards. Enforce and encourage the use of these standards by coaching, mentoring, frequent code reviews, and praise. Lots of it.

We are no longer bound to the limits of first and second-generation compilers. Software projects are growing exponentially in scope and complexity. The need for clarity is now more acute than ever.

Start the project out right. Don't intend to go back and add the commentary or proper conventions later on. Start now. Write it down. Make it official. Read it, study it, and memorize it. Then, like the commercial says, just do it!

Please send any comments to Jeff Gainer.

Copyright © 1996 by Jeff Gainer. All rights reserved.

End of transmission