Talk in code

Last week we had an extended discussion at work about how we were going to implement a specific feature.

This discussion hijacked our entire Scrum sprint planning meeting (yes, I know, we should have time-boxed it). It was painful, but the guy who was going to implement it (yes, I know, we should all collectively own our tasks) needed the discussion: otherwise it wasn't going to get implemented. It certainly wasn't going to get broken into short tasks until we knew how we were going to do it.

Anyway, asides aside, I came out of that discussion bruised but triumphant. We had a plan not only on how to write the code, but also how to test it. I believe the key thing that slowly led the discussion from a FUD-throwing contest into a constructive dialogue was the fact that we began to talk in code.

There are two facets to this principle:

1. Show me the code

As Linus once said, "Talk is cheap. Show me the code.".

If you are at all disagreeing about how what you're doing will work, open up the source files in question. Write example code - modify the existing methods or sketch a new one. Outline the classes you will need. Code is inherently unambiguous. White board diagrams and hand-waving are not.

Why wouldn't you do this? Fear you might be wrong? Perhaps you should have phrased your argument a little less strongly?

Is this slower than drawing boxes on a whiteboard? Not if you include time spent resolving the confusion caused by the ambiguities inherent in line drawings.

Does UML make whiteboards less ambiguous? Yes, if all your developers can be bothered to learn it. But why learn a new language when you can communicate using the language you all speak all day - code?

2. Create a formal language to describe the problem

If your problem is sufficiently complex, you may want to codify the problem into a formal (text-based) language.

In last week's discussion we were constantly bouncing back and forth between different corner cases until we started writing them down in a formal language.

The language I chose was an adaptation of a Domain-specific language I wrote to test a different part of our program. I would love to turn the cases we wrote down in that meeting into real tests that run after every build (in fact I am working on it) but their immediate value was to turn very confusing "what-if"s into concrete cases we could discuss.

Before we started using the formal language, the conversations went something like this:

Developer: "If we implement it like that, this bad thing will happen."

Manager: "That's fine - it's a corner case that we can tidy up later if we need it."

Developer: (Muttering) "He clearly doesn't understand what I mean."

Repeat

After we started using the formal language they went something like this:

Developer: "If we implement it like that, this bad thing will happen."

Me: "Write it down, I tell you."

Developer: (Typing) "See, this will happen!"

Manager: "That's fine - it's a corner case that we can tidy up later if we need it."

Developer: (Muttering) "Flipping managers."

Summary

The conversation progresses if all parties believe the others understand what they are saying. It is not disagreement that paralyses conversations - it is misunderstanding.

To avoid misunderstanding, talk in code - preferably a real programming language, but if that's too verbose, a text-based code that is unambiguous and understood by everyone involved.

Note on whiteboards

You can't copy and paste them, and you can't (easily) keep what you did with them, and you can't use them to communicate over long distances.

And don't even try and suggest an electronic whiteboard. In a few years they may solve all of the above problems, but not now. They fail the "can I draw stuff?" test at the moment.

Even when electronic whiteboards solve those problems, they won't solve the fact that lines and boxes are more ambiguous and less detailed than code in text form.

If you all know and like UML, that makes your diagrams less ambiguous, but still they often don't allow enough detail: why bother?