jumpingfish

1. The Shoe Store

I bought a new pair of shoes, yesterday. It was a strange experience.

When we walked into the place, the smell of leather was wonderful. Unlike our previous forays into three (count ‘em, three) old-guard departments stores, this place felt genuine. They were selling shoes, period. Ok, I think there were some other leather things, but this was just a shoe store. They didn’t try to be anything else. As a marketing strategy, it worked.

For example, here we were standing near a shelf at the front of the store. Trudy looked at some boots and said to me, “Wow. I would marry you if you wore these!” (It was primarily due to the influence of the fair and industrious Trudy that we were on this quest in the first place. I can tell you with some conviction that marrying her was the best decision of my life, and somehow I managed to score that without those boots.)

Ok. So this was a place that even we could enjoy. But still, it was a bit strange… 

2. The Shoe Store Process

I found a pair I liked.

“May I try these in 10 1/2?” I asked.

The woman tapped on a hand-held (Honeywell) device.

I walked off to look at other shoes. When I turned around, she was still there. I was puzzled, but I gave her more time. 

She just stood there. Perhaps they were out of my size. Maybe she was just giving me some space before she told me.

“Are you out of my size?” 

“Oh no,” she said. “They’re coming.”

They’re coming. That’s odd, I was thinking to myself. And at that very moment a door opened in the back of the store. A man emerged holding a box. He walked up with an odd smile on his face. He handed the box to the woman and returned to the back.

The shoes weren’t quite right, so I asked for a different pair. The subsequent process was the same: the woman went nowhere; some time elapsed; the man again emerged with a box. 

This time, he was closer to me. So I reached out for the box.

But he didn’t want to hand them to me. I could see it in his eyes. There was panic hidden behind his smiling facade. He looked at me, then at her, back at me. Finally he reached around me and handed the box to her.

3. How It Appeared

I get it. There are laces to be laced, stuffing to be unstuffed. Don’t trouble the customer with trivialities. I get that.

But here’s the thing of it. We were the only ones there, and I was the only customer.

In addition to the saleswoman and this young, silent shoe-transporter who evidently spends most of his working hours hidden in the bowels of the stock shelfs, there was a manager/salesman in the store, too. One customer and a standard store process that requires three people to service him.

The manager spent much of his time at the cash register, typing away at the keyboard, singing along with the hip, piped-in music. The woman was tethered to a handheld cash register satellite. And there was this silent drone-of-a-man who retrieved and delivered boxes from an area in the back.

I pictured the area behind that door as a vast, dark array of shelves stretching out in all directions. I pictured him stepping onto a platform as soon as he received a get-this-box summons, being whisked off to the box’s coordinates and transported back, stepping off the platform and walking out into the full light of the salesroom, box in hand.

The shoe store felt strange, but I ended up buying the shoes.

… Maybe I need to get out a little more.

0. Synopsis

Software developers aren’t good an explanations. They get things backwards, assuming their audience already understands everything. This isn’t good.

1. Mathematicians

I once worked with some guys who were closet mathematicians. No, that’s not accurate. One of was a mathematician. Still, we were doing software development, which means that his math-y nature was in a closet.

In a closet!? What on earth are you saying, man? You haven’t even made your point, and you’ve drifted off course.

Fair enough. Let me start over.

I once worked with some guys who brought a mathematical way of thinking to their software development jobs.

Much better!

Thanks. My bad.

These guys wrote great software — great in the sense that it did great things. But it was also notorious for being an indecipherable edifice. The mere mortals on our team…

There you go again, man. I suspect mortality is not the subject of this conversation.

Dang. Right.

The rest of us really couldn’t understand their system. Although it was amazing for what it did, they were the only ones who could maintain it.

2. Multiply By 2

Now one day, I had a conversation with one of them about a triviality. He was doubling the value of some integer counter, and to so, his code looked like this: x << 1.

Now I’ll admit that there’s a streak of closet mathematician in me, too, but…

Careful…

Right.

Now, I understood what that code was doing. It’s a bit-shift.

And I understood that when you shift a binary value left by 1, the corresponding integer value (x in this case) is changed in such a way that you’ve effectively multiplied it by 2. Of course I knew this. But it was my opinion that writing the code that way obfuscated (in an admittedly minor way) the underlying algorithm.

In my opinion, the code should have been written as x * 2.

3. A Difference of Opinion

 “But David,” they said. “That is what the code says. It says multiply by 2.”

“No it doesn’t,” I said. 

“Yes it does,” they said. “Everyone knows that left shifting is scaling by 2.”

And of course, they were correct.

But that wasn’t my point. The code wasn’t speaking to the reader. It wasn’t saying multiply by 2. The explanation depended on the implicit assumption that everyone already knows that left shifting is scaling by 2.

“The code doesn’t tell me what you’re doing,” I said.

“But of course it does. Quite literally it says what we’re doing,” they said.

I was not satisfied. Although the basic idea was ridiculously simple: double that thing, the code didn’t even have a 2 in it. 

(Mind you, this was a good natured, philosophical discussion — part of made those years so wonderful.)

4. It’s Your Job

Most software developers are not good communicators.

Um…

Wait. I fully concede that this is an unfair generalization, so work with me, here.

Ok.

The same is true of mathematicians, perhaps even more so.

Um…

I know. This is also unfair. But here is my point: this is a widespread problem among technical people, in particular in the software world. Most software developers are exclusively interested in cranking out code. 

To them, it is your job to get to the required level of understanding. It is your job to infer the general idea from the specifics of their source code. Don’t expect it to be self-documenting. Don’t look for explanations. Before you ask questions, make sure that you have combed thru the code to arrive at the same fidelity of understanding that they have. Failure to do this is laziness on your part.

To use the example above, it is your job to see beyond the bit-shifts.

5. Backwards Speaking

Now, the problem with this bit shifting example is that it trivializes the point I’m trying to make: most developers speak backwards.

Their code, comments, documentation and verbal explanations usually start from an assumption that you already understand. Their approach to explaining their system is to demonstrate that the system conforms to this assumed understanding.

This is backwards. 

The audience almost never has a shared understanding with you. Your explanations, documentation, comments and code (yes, source code) should proceed from an assumption of non-understanding and strive to bring the audience up to speed. In the case of the trivial bit-shift example, the code patently does not say double this thing. You must map from the bit-shifting to the general concept yourself.

At best, this tendency among us is laziness. My contention is that it is pathological. 

6. On Interviewing

This isn’t just a philosophical point. 

It is popular in the software business to throw out a gauntlet of technical brain teasers when interviewing for developers to fill a job. Search for interview questions online. You’ll see what I mean. If I ran a software company, I’d forbid this. 

One of the problems on software projects is a lack of understanding. This shows up at multiple levels: a lack of understanding what the problem is we’re trying to solve, a lack of understanding understanding what the approach a colleague is using in their code, a lack of understanding how this old code works. If I ran a software company, I’d interview candidates for their ability to communicate well, to help the audience reach a shared understanding. 

Don’t get me wrong. I am not implying that truth, love and understanding is the only task ahead of us. Still, at my company, it your job would be more than writing code that works. It would also be your job to share enough information that someone else could quickly understand what you did and why you did it that way.

If you wanted me to hire you, you would need to speak (in code, in comments, in documentation, in presentations to your peers) straightforwardly. I would want you to show me in the interview that you can do this.

7. This is Important

This is a bigger problem than we generally recognize.

Software is expensive, and in the long run a major portion of that cost is that developers typically do a poor job of explaining things. We consider it a right of passage that other developers must dive into the code before asking questions. We only value whether the code works and whether is runs fast. We undervalue clear explanations. We discount the important of shared understanding. We don’t think in terms of an audience that we need to bring up to speed.

We speak backwards, assuming too much. And there is a hidden cost implicit in this. It’s a big problem, and we need to do better.

Time for a little something…

I went to the refrigerator and pulled out the last of the raspberries and some half-and-half. And I put them into a brown-eyed-susan bowl.

My taste for fruit has not returned, so I did not get the enjoyment on my tongue that raspberries bring, although I suspect my taste buds are locally happy even if my brain didn’t globally register a thing. (Or maybe even that isn’t true. Maybe those taste buds are shot. Still, I choose to behave otherwise.)

In any event, the joy of this was the bowl. 

Some of you might know these brown-eyed-susans.

For those of you who do, you will remember summer days of picking raspberries on Stonewall Road. Of mounds and mounds of them for breakfast, for snacks, for just about anytime. And you might also remember those brown-eyed-susans on the plates and the bowls and the juice pitcher and the salt-and-pepper shakers that were in that kitchen that looked out onto that yard where those red raspberries used to grow out beyond the euonymus-topped rock garden and along the line of Cedar trees.

Maybe I didn’t taste the raspberries tonite. But they sure were good.

Saturday morning. A storm has just passed over and is receding into the east. The rumbling thunder is leaving Central Texas behind.

She walks into the study. Standing in the doorway with a smile on her face, she claps her hands contentedly, seemingly just as pleased as Charlie who is curled up under the desk with his eyes closed now that the thunder and lightning are gone.

I look up at her flashing eyes. (Beware! Beware! I think to myself.) 

She claps her hands again.

“Cleaning cycle has begun,” she says.

You see, we entered the late twentieth century a few months ago and got a coffee maker that’s got some automated features, including a warning light that comes on after so many uses telling you to run it thru a cleaning cycle.

“Cleaning cycle has begun,” said the fair and industrious Trudy.

I need not explain further this aspect of her moniker, industrious. The Mr. Coffee cleaning cycle and her joy in triggering it is really all the explanation you need. 

A cold wind blew out of the north-northwest. The thermometer never topped 60 during the days, and it plunged into the 30s at night. But the sky was blue, and at times the sun was warm. (This, mind you, comes from a Texan who left 90 degree days in brief exchange for the wind and a fire burning in the wood stove all day long.)

It was spring — time to pull the sections of dock off the beach where we left them last fall and hook them together in anticipation of still distant summertime celebrations.

These were my compatriots.

And this was the fruit of our labors.