June 96 - The Veteran Neophyte: Manual Labor
The Veteran Neophyte: Manual Labor
JIM MENSCH
As a 14-year Apple veteran, why would I be writing a "neophyte" column? It's
true that I've written system software for many Apple computers and I've been
in every tech support capacity that Apple has ever dreamed of. I'm writing this
because I'm in fact still wet behind the ears; I learn new things every day
here at Apple. Most of what I learn involves problem solving and debugging. I
believe that creative problem solving is the one trait that separates a great
programmer from an average programmer. Great programmers must hone their
problem-solving skills all the time, whether at a computer or not. In fact,
sometimes examining how day-to-day problems are solved can help us develop
proper coding and debugging skills at work. Here I'd like to relate a little
fable to illustrate this point (the names have been changed to protect my
automotive pride).
Bob and Stu were working on a primo 1963 Dodge Dart that they had just bought.
It was a classic: push-button transmission, cherry upholstery, straight body. A
classic car with a classic problem: it had been run dry of oil and the engine
needed to be rebuilt. Flush with confidence (having just completed an engine
rebuilding course at the local community college), Bob said, "No problem, man.
Let's rebuild it ourselves; how hard can it be?" That, I suppose, was the first
mistake.
So, Bob and Stu set out to rebuild the engine, using all new parts. A scant two
months later, the ten-hour job was finished. Finally they were ready to install
the engine. Struggling to get the 1000-pound engine into the car and onto two
very small bolts that hold it at an angle too obtuse to allow it to drop in
straight, they were cussing and cutting themselves constantly.
After a while it dawned on them that things were not going as planned. In a
moment of brilliance, Stu said, "Hey, what does the manual say about installing
this thing?" The manual! Every good car mechanic has a manual and follows it.
Why didn't I -- er, Bob -- think of that? Reading the manual, they found that
the torque converter (a big heavy round thing with teeth on it) was supposed to
be mounted not to the engine but to the transmission!
They pulled out the engine and struggled for an hour to get the converter
mounted to the transmission. After this the engine went in relatively easily
(with the help of Thom the helpful Brit). Having connected all the hoses,
belts, doodads, and whatnots, our intrepid pair looked at each other with giddy
anticipation. "Could it be that we're ready to start this thing?" they
wondered. So they tried to start it -- and they failed to start it. Just as
with every major programming project, they had put in countless hours, and when
the time came to fire the baby up, nothing happened.
It was time to debug this problem. "Hmm. Seems like a compression problem. Do
we have compression?" asked Stu. "Yup, it's low, about 60%, but I guess that's
because the engine hasn't been broken in yet," replied Bob. Were the plugs
firing? Ground one side, turn out the lights, look for the blue spark: of
course they were firing. Was the gas getting to the carburetor? Not yet, so
they siphoned some up and tried again. Still no go.
So they started looking at the esoteric stuff. Was the timing chain on
correctly? Well, we have compression, and it seems that we shouldn't if the
timing is wrong. Three hours later, after Bob browbeat Stu into agreeing that
the timing must be correct, Stu browbeat Bob into testing it anyway, since
while Bob talked a good game it was always possible that he was wrong. They
partly disassembled the engine and watched the little valve bits go up and
down, and sure enough the timing was right. A victory for Bob, hollow as it may
have been.
They continued to argue about what the problem could be, and finally decided to
let it rest a while. This went on for weeks, until one day Bob remembered
something that his teacher told him in class: a tablespoon of oil in every
cylinder will get the seals sealing so that an engine could start. Could it be
that easy? Could it be that the first thing that they had looked at -- the
compression -- was in fact what was preventing the engine from starting? Bob
put a little oil in each spark plug hole and the mighty engine roared to life!
Our heroes stood dumbfounded at first, then quietly patted themselves on the
back for such a fine job. Months after they had started their odyssey, they
finally got the beast running.
The first thing to notice is that reading the manual was not the first step Bob
and Stu took toward solving their problem. Neglecting to read the manual cost
them hours of avoidable frustration and rework. Like
Inside Macintosh,
automotive manuals contain many hidden gems that are there for the asking. For
instance, the shop manual didn't explicitly say, "Don't be a moron; the torque
converter stays attached to the transmission!" but it did say, "Step 9. Remove
torque flex plate screws, leaving converter attached to transmission."
Inside Macintosh contains many such tidbits waiting to be found. For instance,
I was recently asked by a developer why a particular call to close a window
wasn't causing the window behind it to redraw properly (it was leaving a
desktop-patterned hole behind). Examining the problem a little further, we
found that a resource that was needed had been purged and wasn't being
reloaded. The code was smart enough not to crash when the purged resource was
discovered, but it didn't seem to be able to reload the thing. As it turns out,
the developer was using a rather strange strategy for manipulating the ResLoad
attribute of the Resource Manager. He was turning it off when he wanted it off
but not turning it back on again right away; instead he would turn it back on
when he needed it on. I pointed out to the him that this was the problem, and
he said, "I've been programming the Mac for almost 10 years and I've never read
anywhere that the Window Manager assumes ResLoad is TRUE!"
While he's right about this on the surface, if we look we find that Inside
Macintosh warns in the SetResLoad description that "If you call SetResLoad with
the load parameter set to FALSE, be sure to . . . set [it] to TRUE as soon as
possible. Other parts of system software that call the Resource Manager expect
this value to be TRUE." (This has been in there so long that Caroline Rose
wrote the first draft of it!) Since the WDEF is system software, it assumed
that ResLoad would in fact be TRUE. After I pointed this out, the developer
decided it was time to break out those manuals that had been collecting dust
for so many years, and revisit some of the documentation he thought he had
remembered.
Another lesson to learn is that when problems arise, don't spend hours plodding
through esoteric logic. First think, "What's the most obvious cause of this
problem?" You might recall that Stu was right when he suspected a compression
problem. By discarding the obvious without first examining it fully, we risk
costing ourselves days of work only to find out that we were right all along.
As a seasoned programmer, you'll learn that you can get a feel for why a
problem exists. You may not have any ready logic to explain why an event
occurred, but you might have a feeling anyway. Go with that feeling. The
obvious things are the easiest to check (but don't make it too easy and stare
past the real trouble). They're also usually the quickest to fix. Looking there
first can save time, effort, aggravation, and lots of cussing. In my 14 years
of problem solving for Apple, I've found that the simple, obvious solution is
right 90% of the time.
Why did Bob and Stu retest the timing, anyway? Experienced troubleshooters,
they realized that simply arguing about a point may lead to a conclusion, but
any conclusion that can be tested should be. Logic dictates that the cam shaft
can be 180deg. out of phase (for every rotation of the cam shaft, the
crankshaft rotates twice and thus will be in the same position at 0deg. cam
rotation as 180deg. cam rotation), but you should check it anyway if you're
stuck. It's easy to get your logical conclusions backwards and get your
crankshaft 180deg. out of phase. On a car this might result in outright
failure, while on a computer it can mean more insidious things.
I recently needed to use the Power Manager to control screen dimming, drive
spindown, and CPU sleep. All of the calls had a "get" function that returned a
Boolean, TRUE if the feature was on or FALSE if it was off. Strangely enough,
two of the "set" calls required a value of TRUE to enable the feature but one
required TRUE to disable the feature. I spent hours looking at the complex
logic of IF statements before I simply watched it all go by in MacsBug and
noticed that I was sending a TRUE value to a call named Disable. Going back
through my logic again brought the error right out.
If you've learned anything from the above tale, good. Remember, manuals contain
quite a lot of information and they're a good place to start. Also remember
that this isn't rocket (or automotive) science. Think simple thoughts; don't
create extra work for yourself.
JIM MENSCH (mensch@applelink.apple.com, AppleLink MENSCH) has spent the last 14
years as a wage slave at Apple. Before that he did real work that involved
cleaning and lifting and toting stuff and working with tools. While his mother
is his real inspiration in life, he looks to the relaxed masses for guidance.
An avid book collector and cook, he has absolutely no time for computers when
he's not at work. His personal motto is "Eat more beets."*
