Nerd Business

18
Apr

Demo Driven Development

An examples folder is commonly included in source code repositories. You may have seen them. They typically show a handful of use-cases for the code so you can see how it works and how to use it.

A library or a framework will often include these kind of example folders. But how about for your application?

I'd like to suggest a technique which expands upon this familiar examples concept, yet is used in the context of building a single application, and which boasts some of the key advantages you get from another familiar development strategy...


Test boring, demo fun


Testing is a popular software development technique in whereby you write a separate script to run against your application code which is intended to test the given functionality of said code.

In other words, the test verifies that your code does what you expect it to do.

If the test fails, you know something has gone awry.

And by running tests routinely, as you develop and expand your codebase, you can find out when something breaks - the moment it breaks - instead of finding out perhaps days, weeks, or months later when your application suddenly crashes in production.

Of course, this is optimistic. The reality is that making and fixing tests for your code can be just as time consuming as the writing original code itself! So there are some mixed opinions about the merits of testing; not to mention dozens of different techniques, methodologies and libraries one can explore in this regard.


How to setup a demo


A test alerts you when your code has stopped working.

A demo takes it a step further, by ensuring that the code is always working.

When a test fails, you have to fix code. The main idea with a demos is that they never fail. Once complete, you seal it off and move on. So that next time you want to run said demo, you can be 99.9% certain it will run without a hitch.

The above graphic is an example of how you might organize the demos.

There are two types: frozen and live. The live example uses assets and dependencies found in your production ready app. The frozen demos are self-contained; including all files and assets required to run it in isolation.

By keeping your demos in a separate repository, you get separation of version history enabling you to document progress on all those wild experiments - while keeping the clutter out of your main app. Plus this way, you don't have to think twice about adding databases/dumps or other excessive files that each of the demos require.

For the live demos you could symlink back to your main application folder, or just store them in a demos folder in the main application repo itself (my example above which splits each demo into two subfolders may be a tad overkill).


Developing demos


The other nice benefit to making demos is the low-barrier to entry; it's easy to jump in and start coding on a new idea or feature you want to see in the main app. Without the worry of breaking things or maintaining compatibility (that part can come later).

Just start with a copy of the last demo you made - or a fresh clone of the latest master branch from your main application. And hack away.

When the demo does what you set out to make it do - I might suggest formalizing it with a special commit to signify the milestone.


git tag -a explosion_v1 -m 'Explosion happens. Cool!'

To list existing tags, type git tag or use:


git show-ref --tags

which will show you the specific hash of each tagged commit so that you can easily checkout back to this point in the repo (in the event you need to roll back to see how things worked after breaking said demo with a later commit).


In conclusion


It's a shame when your efforts are neglected simply because of a config problem or some resource is out of place that prevents your code from running like 'you had it the other day'.

Demos are a nice way to guarantee, encapsulate and protect these efforts. And by formalizing them they can perhaps be used as strategic stepping stones to whatever grand architecture you have in the works.