Skip to content

Backwards Speaking

Sat, 27 May 2017, 09:40 AM (-06:00) Creative Commons License

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.

© jumpingfish by David Hasan is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License