From elevator pitch to beautiful code

In school, we’re taught to translate business requirements into code a computer run, but the lack of focus on human readability causes issues. Why don’t we try to put the human first, and then make the computer understand?

An experiment

Let’s do an experiment! How would you explain your project to a non-programmer friend in the shortest way possible, write that down as a comment in your favorite IDE. I’ll follow along with a simple example:

    def main() {
        // go camp in nature
    }

It’s short, clear and concise. It doesn’t contain any unnecessary details. Let’s translate that to code.

    def main() {
        // go camp in nature
        goCampInNature()
    }

Well… that was easy! :)

So now your friends ask you some more details… how will your day go?

    def goCampInNature() {
        //pack
        //drive to the forest
        //put up tent
        //make a fire
    }

A lot more detail here, yet not too much. It doesn’t matter which car it is, it would be silly to already explain that you will have to unfold the tent, put in the poles and pound some pegs into the ground.

Making that into code is slightly more complicated:

    val you: Person
    val house: House
    val car: Car
    def goCampInNature(campSite: Location) {
        val gear = you.getGearFrom(house)
        you.driveTo(location, car, gear)
        you.putUpTent(gear.getTent())
        you.makeFire(campsite.getWood())
    }

Important here is that we’re describing the process from the business stakeholders point of view: A person will go camping and will have to execute 4 actions to be camping.

Single layer of abstraction

Unless prompted by your friends, they’ll likely not care about what exact gear you pack, how you pitch a tent, or how you make a fire. So we don’t bore them with the details.

What you see at work here is called “single layer of abstraction”. One layer of details at a time. Which I would argue is the most important way to increase the clarity of your code!

Lets see what happens if you mix 2 layers:

Imagine that you were explaining this to a friend, and all of a sudden you go into a rant about the intricate details of making fire. Isn’t that a bit weird? On top of that, if you’d like to only explain how to make a fire, you’ll have to include the whole process of driving to the woods, which also makes no sense! And how long would it take your friend to realize that you are describing how to light a fire?

    val you: Person
    val house: House
    val car: Car
    def goCampInNature(campSite: Location) {
        val gear = you.getGearFrom(house)
        you.driveTo(location, car, gear)
        you.putUpTent(gear.getTent())
        val wood = campsite.getWood()
        val splitWood = wood.split()
        val crumpledPapier = you.crumple(gear.getPaper())
        val stack = you.stack(crumpledPaper, splitwood)
        you.light(stack, gear.lighter())
        you.blow(stack) 
    }

So… what if we separate it?

    val you: Person
    val house: House
    val car: Car
    
    def goCampInNature(campSite: Location) {
        val gear = you.getGearFrom(house)
        you.driveTo(location, car, gear)
        you.putUpTent(gear.getTent())
        makeFire(campsite.getWood(), gear.getPaper(), gear.getLighter())
    }
    
    def makeFire(wood: Wood,paper: Paper lighter: Lighter) {
        val splitWood = you.split(wood)
        val crumpledPapier = you.crumple(paper)
        val stack = you.stack(crumpledPaper, splitwood)
        you.light(lighter, stack)
        you.blow(stack)
    }

You see clearly how it nicely separates your stories into parts, and as a bonus when somebody asks “how do you make a fire?” you know exactly where to go!

This was only a small and simple example, but it shows nicely that starting from the story, or the business process is relatively easy and almost gives you the separation of concerns and layering of abstractions for free!

Design patterns

An important note to make here is that this was a relatively simple use-case. There were no choices to be made like taking a train or bike vs taking the car. or setting up a hammock instead of a tent. For these you’ll need to use Design patterns for example. The key here is to start without any of these variations, figure out your layers and then add the variations.