Stop trying to code your way out of the problem
By: Christopher Laine
Tags: Development, Software Development, Programming, Software Engineering, Architecture

Abstract

Here’s the situation. I need to build a test harness to verify that when my software sends / receives data to some other system (a system outside my control), the data is not only received, but is in fact the data I expected to have been sent.

Pretty standard test harness stuff, right? The testers say they need this for manual and for automation testing suites. Internal customer need. Great.

So the developer starts rattling off software tools / languages we will use to build this test harness.

Wait, what?

Not so fast, cowpoke

How did we get from a high level need to implementation that fast? Where are our requirements? Where are our user stories? Where the heck are even some simple sequence / flow diagrams to describe whussup?

Well, the dev imagines he/she has these already in their head, so time to get to the fun stuff, the cutting code stuff, the implementation.

Sound familiar?

If so, then do everyone on the team a solid and pull the brakes before the conversation carries on down this line any further.

We’ve skipped a step, and it happens way more often than we might be willing to admit.

Measure Twice, Cut Once

Before I can build anything, I need to understand as best I can what I’m building in order to get to work. I’m not just talking software. You want to build a birdcage, a deck, patio furniture? Any and all of these things (including software) require you to have a clear picture of the item being built, and from this picture you can set off to build it right the first time.

Measure twice, cut once is the old adage. That is, before you do any work, make sure you’ve double-checked your measurements before you do anything. The more which you understand what you’re building, the better the chances you will be successful in building it.

And in most industries this still holds true: I won’t buy a car or a house that wasn’t modeled off a blueprint. I don’t buy a mobile phone which someone just slapped together without specs or detailed instructions on how to manufacture it.

In software, however, we often allow ourselves to be lulled in this regard. Terms such as “Agile” and “MVP” have crept in over time, and when misused / misunderstood, come to stand for “Just start coding and we’ll figure it out when we get to the end”.

Everyone is guilty in one way or another. Devs do it because that’s the stuff where they have expertise. POs do it because they want to see “productivity”, to see those stories keep moving. People sometimes do this because that’s all they know, that’s how they’ve always done it.

Trust me when I say: Stop doing this. Stop trying to code your way out of the problem.

What should you do?

Now that we’ve decided to build this test harness, and WAY before we pick tech / solutions, let’s just nut out the expected behaviours we need from our test harness.

An easy way to do this is just get a whiteboard, and draw a simple set of sequence diagrams showing the flow from start to finish.

If you are keen and want to learn something new, try using PlantUML support for sequence diagrams to show the actions of all involved in a simple, easy-to-understand picture.

At the very minimum, you and your team should agree to and WRITE DOWN what the expected business behaviours are in your code changes. This is the contract, the blueprint of what is required. It is not a technical blueprint, but it IS a blueprint of what is needed for your software to be truly successful and bug-free.

Here’s a simple diagram / plantuml blob to show you what I mean.

title Tester and the TestStub, Scenario 1: Send data to our API

actor Tester Tester -> TestStub: Send data to our API

TestStub -> OurAPI: POST /some/url/ DataBlob

OurAPI -> TestStub: 200

Tester -> OurAPI: GET /some/url/for/datablob

alt if data is found

OurAPI -> Tester: 200 DataBlob

note left

:)

end note

else return nothing was found

OurAPI -> Tester: 404

note left

:(

end note

end

As you can see, this is pretty basic, and doesn’t take a lot of effort to create. What it does for the team’s understanding far outweighs the effort, and ensures everyone is clear about what the dev is going to make.

Why do I need this?

The question which often arises at this point is “Well what do I need this for? I know what’s being built, so why not just build it?”

Because I will bet dollars to doughnuts you DON’T know what’s being built. You are likely the victim of your own assumptions of what does what in this little exchange, and there is a strong likelihood that you could be assuming things no one else is assuming. The more complex the problem space, the more likely your assumptions are off-base, even by a little bit.

Because writing down / diagramming each flow is a talking point for the team, something which helps everyone to be on the very same page as to what is being built, and thus what is going to be tested and delivered to our customer. These kinds of talking points lead to discussion, debate, clarification, all the things which make it ever more clear what is going to happen at a business / logical level.

Because it’s all well and good that you ‘know it’ now, but you in a year or more, or a new team member, will have no way of knowing exactly what the test harness is, or what it actually does. Such documentation / diagrams / etc are a good way to keep knowledge debt at bay.

Because you will thank me for it when you approach software development this way, after even just one try.

In the End

Next time you find yourself or someone leaping to implementation too soon, give this exercise a go. See if it helps. You can always go back to coding your way out of the problem if this isn’t for you.

However, I have a sneaking suspicion that after a couple times doing this, you will see the benefit for all concerned. Coding your way out of the problem is often the cause of — not the solution to — delays and bugs and rework.

Take some time to fully understand what you’re building before you crack on to build it.

Hope this helps