Story Driven Development with DSL and REST December 8, 2018

This article describes how to implement large-scale, high-performance, interactive single-page and other designs without using any JavaScript and without having to be a professional programmer.

Part 1 - Story Driven Development

Every new website project starts with a "story"; a narrative that describes the appearance of the site and the way it responds to user interactions and other events. Stories can be visual (picture-based), they can be expressed as text, or they may simply exist as conceptual entities in the shared awareness of the development team. The last of these leaves no permanent record other than some emails and Slack messages, but in most cases the website itself displays its purposes clearly enough.

Story Driven Development (SDD) may or may not be a recognized term, but I use it here to mean a formal, documented process with just 3 steps:

1 Write the stories
2 Do the development
3 Test the result against the stories

SDD doesn't care how you do the development, only that it's following the stories. We start with the expressed requirements of the client, formalized as design documents and used to verify the final product. Along the way there may be many steps  bundled together as "Do the development", and for all but the most basic websites a program of some kind will run in the browser to control aspects of the design. JavaScript is now the only game in town as far as the core programming language is concerned, but it is increasingly layered with tools and frameworks like Angular, React and Vue. These are all tools for professional programmers that leave little space for the client to be involved in the development process and little opportunity to verify progress until the final product is delivered.

For over 50 years the software industry has had a poor record of delivering what is wanted. Projects overrun on both time and budget and frequently fail to work as requested. Sometimes they collapse in unrecoverable heaps, but the response of the industry is usually to throw more complexity at the problem in an often futile attempt to squash bugs before they occur. The consequence, even for initially successful projects, is an ever-growing dependency on a coterie of highly-paid, highly trained software engineers who will not be around years later to maintain the products they have built. The result is a downward spiral of reliability and a loss of fitness for purpose, as many customers are unwilling or unable to afford the equally high cost of maintenance.

But it doesn't have to be like this. With more emphasis on the stories themselves we can build code that is understandable by product owners as well as software engineers. It's a fundamental principle of Open Source that "with enough eyeballs, all bugs are shallow", and it goes without saying that the easier your code is to understand the easier it will be years down the road to find people who can be safely trusted to maintain it.

Let's look at an example.

Suppose we have a web page that displays some paragraphs of information. If there is too little content the message may not be properly conveyed, but too much may overwhelm users and cause them to give up. So we decide to compromise by using a 'concertina' design pattern, putting a "more..." link at the end of each topic, which when clicked causes a popout block - further text and/or images - to be added to the topic. A corresponding "...less" link in the new text restores things to their previous state.

The basic story for invoking this feature looks something like this:

"When the user clicks the More button...
1 Close any popout blocks that are open
2 Hide the More button
3 Make the popout block visible

With the help of our HTML designer let's now rewrite step 3 in terms that relate to the content of the web page:

Set the display style of the div whose id is "popout-1" to "block"

This is fairly clear and unambiguous, though the syntax is a little clumsy and could be improved. More importantly, you may need to do more than one thing to the popout div, such as giving it a background color or a border. To avoid repeating the central clause (the div whose id is "popout-1") each time, let's create a named entity that we can use whenever we want to refer to the div. We can call it Popout1 so it's easy to see which id it relates to. The action we want to perform is to attach this entity to the div element in the DOM:

attach Popout1 to the div whose id is "popout-1"

Now when we want to show the text, all we need to say is

set the display style of Popout1 to "block".

When a story like this is translated into JavaScript it leaves the normal, everyday world and enters the domain of the programmer. From here on, every addition, every change, however simple, needs a programmer to cast the necessary magic spells.

However, although the story is expressed in ordinary English it's actually an unambiguous description of some actions. This is really what defines a computer language, so in an ideal world there would be a compiler able to handle instructions like these. The good news is that languages of this kind do exist - they're called DSLs - Domain-Specific Languages. Rather than catering for general-purpose programming concepts, a DSL uses a syntax and vocabulary that have particular meaning in the domain for which the DSL is written. Here in the domain of the web page it's all things relating to browsers and what they do.

DSLs can be used by programmers and non-programmers alike, though the former can be expected to produce better code more quickly and with fewer bugs. The code may not be simple - a DSL script may be asked to do complex things and if complexity is really there it's not possible to hide it just by writing it differently. The difference is that no matter how complex a DSL script becomes it can still be read and understood by anyone having sufficient domain knowledge, without also having to be a JavaScript expert. Every command in a DSL script has a real-world meaning and it takes only minutes to learn the essential features of the scripting language.

A good DSL has other advantages. It can offer a built-in debugger that allows you to step through the script, examining variables as you go. Most bugs are quickly revealed by this technique. And in a WordPress context, much of the coding can be done by people with ordinary Editor rights on the website. This is because DSL scripts live in the page with the HTML, so it makes a DSL very convenient to use for simple web pages that only require a small amount of coding to handle their features. No need to find a place for custom JS files; everything is done using the WordPress editor.

You may have realized that the DSL I've been talking about all this time is EasyCoder. Others may exist of course, and I would encourage you to look out for them, but I'll continue to focus on what EasyCoder offers to website builders.

You may also have gained the impression that because the examples we present are simple, EasyCoder is only for simple websites. This is far from true; most examples have to be simple because that's the nature of examples. In fact, EasyCoder has some industrial-strength features that I'll describe in part 2 of this article.

Part 2 - The power of DSL and REST

Categories: Uncategorized