AA, BB, CC, and DD

I am not making it up. AA, BB, CC, and DD were the key driving variable names I found in the code which I had inherited from the investment bank’s new Wunderkind. We will call him “Will”.

The astute reader will be rolling their eyes at the obviousness of this tale and the inevitability of its moral, one anticipated long ago by Confucius in his proposed reform, Zhèngmíng, the “The Rectification of Names”.

“If names be not correct, language is not in accordance with the truth of things. If language be not in accordance with the truth of things, affairs cannot be carried on to success.” — Confucius, Analects, Book XIII, Chapter 3, verses 4–7, translated by James Legge

I was working as a body shop consultant in easily my most “Work In Tall Buildings” job ever. One day Will came on board, totally not GQ, scrawny, smart, energetic. I had no idea he was a first round draft pick, destined for greatness. An employee, by the way. He dives in and starts churning out a front-end application, learning the HLL and OS and tools all at once, a man after my heart. A year later he will have invented a 4GL adopted by the whole bank, using the programmable text editor Teco to convert tight scripts into full-blown applications, and won a mention in the bank’s annual report.

Will was good and respected in high places.

At one point he mentions to me a problem. He wants users to be able to make discontinuous menu jumps, say, go sideways without backing up to the menu above (yeah, this was the good old days of modal interfaces) and COBOL would not go sideways. ie, He was using HLL recursion to handle nested menus.

I suggested the obvious: no, you cannot call sideways in a structured approach, you have to return from the called function with a “message” always checked by the caller to see if the user should be taken somewhere else.

“Great!”, Will yelled, and tore off to code it up.

A couple of weeks later I have inherited the system. Will was smarter than I: as soon as he had chalked up a prototype win he told his boss to “get some consultant to maintain it”.

Moi.

So there I am working on the first RFE and I am perusing the code trying to figure out how the hell it works and I find myself slowed down a bit by the variables that pretty much controlled everything: AA, BB, CC, and DD.

So I wander over to Will’s desk, clear my throat, and Will looks up.

“What’s up,” he asked cheerfully.

“Will, I am looking at the code,” I began. “AA? BB? CC? DD?”

Will burst out laughing.

“Those are just temporary variables!” he protested, laughing even more.

“They control the entire program flow,” I demurred.

“Well, change them if you like.”

As I said, Will was a smart cookie, he was wiping his hands of the whole app.

Tilton’s Law: Spend more time on the variable names than on the algorithm.

Tilton’s Rule of Abbreviation: Abbreviate no name less than seven characters long and then only if a good abbreviation is no more than half as long. Rounding down.

Now it turns out that one of the things I like to do when working on OPC (Other People’s Code) is to stare at it and stare at it and when I see some crucial variable playing a big part in things and its name is getting in my way I pick a better name and do a global change, rinse, repeat until the damn code makes sense.

The only reason I had gone to talk to Will was the same reason we pay to see a two-headed sheep at the carnival.

Two hours into the renaming I had come up with decent names for AA, BB, CC, and DD (that last one turned out to be three different variables) and I was making the global changes eyeballing each as I stepped through the source and after one such change, forgive me, I will never in my life remember the specifics, but imagine you have just made the substitution and are now looking at a line of code that says:

total-weight = total-weight + this-length

I did not feel completely comfortable with that edit, so I called Will over so he could see it in context on my terminal.

Did I mention he was a smart guy? Two seconds into my explaining how I had gotten to that point he exploded.

“Great!” he yelled. “I gave up on finding that!”

Smart guy. Tough bug? He just moved on and chalked up the win. Let some consultant take over the code, run into the bug, and figure it out.

But there you have it. A bug so hard to find that a very smart programmer gave up on finding it, and someone who did not even know the bug existed changed a few variable names and the bug ran out waving a white flag.

Explaining the corollary to Tilton’s Law:

If the names are right, the algorithm will write itself.

Bad names in programming are rarely so egregious. The classic would be names like “lmove” and “rmove”, where “l” and “r” stand for left and right. Visually, when debugging the bizarre travels of our game widget, they are invisible.

I hate typing, too. Do not do that. And do not do something else Will did.

Do not tempt the programming Gods.

Do not sniff at craft.

Will sniffed at his craft. I once spent two hours helping a noob find a bug who had tried to get away with a Cobol GOTO, despite a clear shop rule banning them. The GOTO was too far above the likely place in the code for me to spot it on our 24x80 VT-100 terminals.

When traces suggested the impossible, I opened my mind and scrolled way up, finding at once the GOTO that bypassed the logic we had been staring at for hours.

Will knew AA, BB, CC, and DD broke all the rules, but he hated typing as much as I did and thought he could get away with it.

Tilton’s Law: Do not tempt the programming Gods. More examples.

If you have the thought, “I do not need to check this”, check it ten times.

We never coded a test, but our 100KLOC Common Lisp program (think “500KLOC Java”) never failed during a demo, even though my buddy and I customarily made massive feature enhancements until 2 AM the night before.

Never failed, except once. And a non-programmer on the team called it.

To dazzle our potential clients, we had gotten a beefier demo machine and installed the software there.

“Shouldn’t we test it before the demo?” our civilian asked.

“No,” my buddy reassured her, I learned later. “It will be fine.”

An hour later the demo crashed as soon as I launched it.

“We’ll go to lunch,” our friendly audience said. “This always happens to demos.”

Not to us, but I took the life ring gratefully.

Off they went, and three minutes later I saw the problem: the app was writing to a log file assumed to be present. It always was, until the software was installed on a new machine.

Can you say “:if-does-not-exist :create”? Sher ya can.

“It does the same thing” rarely does.

My favorite all-time-ever demo failure was magical.

After a year of development, the user-side VP project manager had come to our basement development war room to cut the ribbon on the acceptance test. The air was electric, all were gathered.

The VP left five minutes later.

What happened?

• The VP takes the seat of honor in front of a terminal, where the app has already been launched. His Eminence will be driving. We call it “acceptance” for a reason.
• With jokes all around, the VP makes himself comfortable. He adjusts the height of the chair, moves the detached keyboard to the perfect spot, and even reaches out to reposition the monitor a smidge, to get the viewing angle just right. The monitor goes dark.
• Hello?
• In adjusting the monitor, the power cord already at full stretch had gotten pulled from the back. No problem, we plug it back in, laughs all around.
• The monitor comes back on showing nothing but ASCII escape sequence noise. No one knows why, so the VP heads out.

The culprit? Someone used VT-100 escape sequences to initialize the monitor forms handling capabilities. That works, but if the power is interrupted, when the monitor comes back on it does not have the benefit of the initializing escape sequence. The forms library, which should have been used to initialize the forms capability, knew how to handle power interruptions.

We did not know any of this, because no one had ever made the power cord fall out of the back of a monitor in a year of development.

Dear Will

The rules of a craft are born of long practice. Craftsmen cannot always justify these rules, but honoring them is why they are craftsmen.

I did my student teaching in Hemel Hempstead, England, a working class satellite of London. One Parent’s Night, a few fathers were doing some carpentry for the classrooms. Somehow I happened to mention that the triangle was the only rigid polygon.

“Ah, Barney,” said one of the fathers. “That is why we always nail a strip diagonally across the back of a cabinet.”

Will, you knew AA, BB, CC, and DD broke the rules of the craft, but you thought it would be OK. My buddy thought we did not need to test on a new box. The forms programmer thought the escape sequence was equivalent to the forms function. Moral?

Do not tempt the programming Gods.