Pre-Code Design: When To Start & When To Stop

Alright, pre-coding design. By that, I mean, the serious thinking one does before one starts typing code into the computer.

The first puzzle of pre-coding design is to identify when to start & went to stop.

Start When You Have A Story

When to start: when a story has been selected for implementation.

That starting condition will be tricky for noobs, so let me blather for a minute. There’s no time to discuss stories in general, but in short, by story I mean “slice of functionality that goes from ‘pixels to registers and back’ doable in less than a couple of days.”

All the way in and out is very important. A couple of days is very important. There’s other very important, too, such as valuable, and some unimportant parts noobs often think are most important. No way we have room to discuss how you get to stories like that, we’re gonna stash that for another day.

Now, don’t go off telling everybody I said they should shut up until we have a story picked. We’re gonna talk, kids. We’re gonna talk, and it’s gonna include design ideas. We need that burble of ideas and insights before we even pick a story, after all. That’s fine. What I’m saying is, don’t take it very seriously. Sketch this, poke at that, look this up, schmooze it all over. That’s fine.

But design that specifies changes at the code level in any detail at all waits until the story has been chosen. You start when you have a story and you’ve decided to implement it.

Stop When You’re Excited BUT Nervous

When to stop: when you are at the place where you feel excited that you’re probably right but nervous that you might be wrong.

This surprises a lot of folks.

People who’ve dabbled in this movement will have encountered a great deal of railing against “Big Design Up Front”, and they think that means there’s no designing allowed. They’re surprised I encourage us to design at all. Relax. The method works for you, you don’t work for the method.

People who’ve trained and worked their entire careers old school, on the other hand, think that this is way too little design. One hears the word “cowboy” among the epithets. Relax. We’re not done designing, we’re done pre-code designing.

“Hey. I think we got it.”

That’s the sweet spot for stopping the pre-coding design. Notice that “think” isn’t “know”.

If You Pass The Big Black Bulldog With The Droopy Eye…

Let me throw out a few “too far” indicators, so you can get a feel for that sweet spot to start with. If you pass any of these points, you’ve gone too far in your pre-code design:

* you think all the thinking is done.
* there’s zero risk.
* you’re so detailed there’s a program that could just translate it directly into code.
* you can just send all the lesser lights out to type it in.

Right? If you see one of those droopy-eyed bulldogs you’ve taken that pre-code design too far.

Keep Going Past Where The Dairy Queen Used To Be…

Well, if we’ve got “too far” indicators, let’s look at some “not far enough” ones.

* you have no idea what files/modules/objects are likely to change.
* you are terrified it won’t fit in a couple of days.
* you don’t know how you’ll respond to a generic failure in the new functionality.
* you don’t know how you’ll enable/disable the new functionality.

When you hit the keyboard, you want just enough to make you feel you know where to start typing. Don’t worry that you haven’t done enough thinking. You haven’t, and that’s the correct situation to be in.

Hey, That’s A *Feeling* Not An Algorithm!

Yes. It’s a feeling, not an algorithm. (The force is strong in this one. <cue eye-roll>.)

There’s no computable algorithm for determining when you’ve done enough design. Very intelligent bozo’s have been trying and failing to find one for quite some time. Or, maybe there is one, maybe one exists, but it doesn’t matter because we don’t know it yet.

And before you bemoan this too much, try to remember: the current non-computability of the software design problem is why you aren’t on the night shift at 7-11. Or hiding from SkyNet in the rubble.

So you’re going to have to go with your gut.

Collaboration May Be Called For

The decision point will vary from one context to another, depending on factors including but not limited to: codebase knowledge, mad geek chops, domain knowledge, really offensive arrogance, number of eyeballs, most recent collossal failure, etc.

In a collaborative situation, people will disagree about their gut feelings. I’ll offer a pro-tip: don’t disrespect folks who are less confident than you. Find a 50/50 compromise, then bias it a little towards the nervous side, and do it explicitly and openly and cheerfully. The time difference isn’t that significant. Good nervous cheer from your pair is very significant.

(On the other hand, I usually resist compromising with corporate handbook nervousness. I especially target here company-wide design rules, which are nearly always borked beyond any ready solution.)

Is That All The Design We Do?

Of course not.

The stopping point above isn’t the stopping point of design, far from it. Remember, we’re talking here about pre-coding design.

When we say we’re ready to code we most definitely don’t mean we’re ready to not design. The real design is just heating up, in fact. All through the implementation process we will be making further design decisions.

The fear is that we haven’t done enough thinking to really solve the problem.

The reason we have that fear is because that’s the situation: we haven’t done enough thinking to really solve the problem.

But I’ll let you in on a little secret. Thinking is done with thoughts. Really solving the problem is done with code. You will never really solve the problem by thinking, you will only ever really solve the problem with the code.

That doesn’t mean we don’t think. It means we think enough to code, then enter a tight little cycle of code-think-code-think-code-think.

Design Enough To Code,

Then Code-Design-Code-Design-Code-Design

Pain And TDD


“We were doing TDD just like we’re supposed to, but at some point it started hurting, so we not only quit, we told everyone else on the interwebs that TDD doesn’t work.”

I met Kent Beck after a couple of years reading and writing around him, at the first ObjectMentor Extreme Programming (XP) Immersion, a wonderful week I’ll never forget, where I met so many awesome geeks and coaches. (Kent Beck, Mike Feathers, James Grenning, Bob Martin, Ron Jeffries, Martin Fowler, and more! You get the idea it was a special week?)

And Beck, answering a question, told the old Smith & Dale joke:

SMITH: Doctor, it hurts when I do this.
DALE: Don’t do that.

(The visuals include a funny wagging arm movement by Smith.)

Don’t Do That!

I chuckled. It was merely years before I grasped the deeper level of this old joke.

One might interpret it as saying “TDD hurts me, so I won’t do TDD,” but that’s actually the wrong way to interpret the joke.

You see, TDD works for some of us. And it works very well.

But it’s really important that you hear what I’m not saying.

I’m not saying that you didn’t — or aren’t — feeling pain. I’m not saying you weren’t — or aren’t — trying. I’m not saying TDD works for us because we’re smart and you’re stupid. 

What I’m saying is that you are not responding to the pain you’re feeling in the TDD way.

Pain Means Something Is Wrong

TDD is not painful.

I don’t mean that it’s not painful in the sense of “you’ll just feel a little pinch”. I mean it’s not painful at all, really.

So when we feel pain while doing TDD, something is going wrong.

The somethings that could go wrong are exactly three:

  • You are working in legacy.
  • You are learning.
  • You are working with code that needs refactoring.

That’s it. There are really no other situations where TDD should be causing pain.

Legacy Pain

TDD can leverage you out of legacy. I’ve done it. But working in legacy is just painful.

The key to successful legacy work is to become a master of extraction refactorings. Before you TDD a change, extract the change site so that it is optimal for microtesting.

When you can’t write a real microtest because of the location or accessibility or complexity, either move, extract, or simplify the code via refactorings. It’s not hard, but it’s tedious as hell, and it takes a certain boldness.

This will help. It will ease your immediate TDD pain, and it will — very gradually — lift you out of legacy work altogether.

But yeah. Legacy hurts for as long as it’s legacy, and there are not two ways about it.

Learning Pain

Most of the time, learning is a source of great joy to us. After all, we’re geeks. That’s what we do, is learn things and delight in them.

But there are some situations where learning hurts. Most of these are situations where you have to learn something while 7 people are shouting at you that if we don’t fix this we will simply all die. Let me tell you, that’s gonna hurt no matter what you do. Suggesting, of course, that we teach people not to do that.

There’s another time when it hurts. It hurts to learn when your current goal is too far over your head.

I have worked from time to time with folks with weak TDD, weak confidence, and weak knowledge of a language or a domain. That’s a painful combination.

If you are stuck at the incantation stage in a language, where you’re just barely avoiding syntax errors, and the fundamentals of the language are not yet within your grasp, it’s sore tempting to drop TDD altogether and just focus on typing the magic in correctly.

But it’s contraindicated. The reason TDD is a great design technique is because it organizes the design. That organization, plus simple extended exposure, is going to be the thing that ratchets your knowledge up most rapidly. Abandoning TDD will slow down your learning, not speed up.

Code Pain

Ahhhhhhh. Now we come to it.

I have a strong belief that code pain is the main reason people leave TDD behind.

And here’s what they’re doing wrong: gritting their teeth and trying to play through it.

That’s not the TDD way. In TDD, when we feel pain we change the code until we don’t feel it anymore. And we add what we’ve learned to our daily codesense.

Codesense isn’t one trick, it’s a thousand. And it isn’t an algorithm. Codesense comes into play at large scales and at smalls. But it all comes from feeling pain and resolving not to feel it any more.

Coming soon to a blog near you: live-action codesense examples, where pain leads to refactoring leads to new design.

We don’t play through the pain in TDD.

We use it to change our behavior & build our codesense.

Your Design Is Broken: It’s TDD, not TDYAR

Think about your last huge unrequited crush.

A real one, I’m talking. A crush so big you go to sleep thinking of your future together, and wake up, ummm, guilty. The kind of crush that great romantic stories are made from, and for. The wobbly-knee’d kind.

And a complete non-starter: when I say unrequited, I’m being clinical in an effort to minimize the likelihood of breaking out into laughter, as doctors and nurses in every ER around the world do.

Now, in that kind of crush, you have a vision, and that vision is glorious beyond compare. It captures entirely your ideal notions of successful love. I’m not going to ask you to describe it. In fact, please don’t describe it. I have sensitive comment readers here. But picture that imagined future, just for yourself.

Was it magnificent? Brilliant? A tale for the ages?

I’d bet it was all this and more.

In fact, there’s really only a single flaw in that entire vision.

That Future Romance Is In Your Head

That tremendous romantic vision is just that, a vision. And when it came time for that blueprint-for-love to hit the shredder we call real life, it just wasn’t up to the challenge.

Thus with your design.

You see, your design lives in your mind, like your romantic vision. Oh, it may have slightly more contact with reality, because, after all, I still can’t believe you thought that — never mind.

And, notice, I’m not suggesting you’re not the greatest software designer in known space. My point in no way depends on you being a sub-par designer. Surely, you’re not a sub-par designer of romantic visions for you, are you? Far from it.

Codeless Designs Are Relatively Worthless

A design in your head elides all messy details, tricky complications, and inevitable exceptions.

A problem your company wants to solve never does.

So how do you cope with this divergence?

You code up your design, and as the working code begins to implement the design in your head, you keep an eagle-like watch out for its inevitable infelicities, and you change the code — and your design — until it is still working and no longer has its problems.

That’s what TDD does. A sketch of a design leads to rolling some microtested working code which is re-designed in microsteps. Red. Green. Refactor. Commit.

Design-In-Head Vs. Design-In-Working-Code

When your starting design meets the emerging design that comes from repeatedly applying the TDD process, there will be clashes. Thankfully, most of them aren’t as bad as that great unrequited love. But, on the record, some of them are.

When it happens, which design is right?

The one in the working refactored microtested code is right.

Your Design Is Broken

That’s hard, but you have to let it go.

Use a mental design to work your way into the code using TDD, and your broken design will become a masterwork of productivity. Ignoring the code’s design in favor of the mind’s, and you will pay a great price, starting tomorrow and lasting until your company inevitably goes out of business.

People rail against TDD.

A great many of them are refusing to confront this basic clash of designs, and they just can’t let go of their mental construct in favor of their silicon one. (The most recent such, from the famous @DHH, reeks to me of this.)

And that explains for me a large amount of TDD criticism, and an even larger number of failed TDD adoption efforts.

If you think TDD is supposed to work w/o changing the shape of your designs, you have missed the point. It is not surprising to me that you find yourself hating TDD.

I see a lot of “TDD and my design clash, therefore TDD doesn’t work”. I’ve seen even more of it lately.

TDD Is Test Driven Development,

not

Test Driven “You Are Right”