title: Breaking the Rules: Refining Prototypes Into Products  
author: Darren Bane  
copyright: 2020 Darren Bane, CC BY-SA  

# Abstract

Recommendations for a process to refine prototypes into production-quality code
are made.
\.R1
accumulate
\.R2

# Introduction

The conventional wisdom is that prototypes should be discarded once the lessons
have been learned,
and the final product written again from scratch.
In the spirit of
\.[
beck 1999
\.]
I argue that improvements in development tools have
invalidated this.

*TODO*: case study

# Literature Review

There is a long history of recommending prototyping as a way to construct
systems.
I would personally recommend
\.[
robertson agust\(i 1999
\.]
and
\.[
pitman 1994
\.]
.

*NB*: I am almost certainly re-inventing a SmallTalk wheel.  However I
argue that Lisp's combination of imperative & OO
is an easier sell to industry
whereas pure OO as in SmallTalk (or logic programming as in
Prolog) is still niche.

A closely related are is that of "specification animation",
quickly writing an implementation of some subset of a formal specification in
for example Z or VDM.
Prolog is a common choice for this, but I choose Lisp instead.

However, as stated in the introduction, this document differs from these in
arguing that it is possible to *refine* a prototype into a product.

# Prototyping

The first step is to construct a prototype,
or in modern terminology a "Minimal Viable Product".
These recommendations follow on from
\.[
robertson agust\(i 1999
\.]
and
\.[
bane 2008
\.]
.

Reasons for choosing Common Lisp include:

* Procedural and object-oriented programming is commonly taught.
* The existence of quicklisp.
  Popularity is not really a reason for choosing Common Lisp over ISLisp,
  but slotting into quicklisp *is*.
* Limit to recommendations from the
  [awesome list](https://github.com/CodyReichert/awesome-cl),
  or [portability layers](https://github.com/CodyReichert/awesome-cl#portability-layers).
* Contrary to a lot of other languages, it is fairly paradigm-agnostic.

At the same time, I want a clean subset of CL,
so cleave as close to ISLisp as practical.

*TODO*: write CDR

It was decided to use the imperative/object-oriented paradigm,
partly for familiarity in industry and
partly for a reduced "impedence mismatch" to current hardware.
The following technology is recommended:

* The SBCL compiler.
* ltk for the view layer.

The following is probably the most work that makes sense
without earning money.

## Coding standards

Even though this is a prototype, attention should be paid to basic craftsmanship.

* Divide the system into packages, using the subset of CL that is
  supported by OpenLisp
* Write one-sentence docstrings for at least each public fun and class
* Use `declare`
  to check the types of parameters in public interfaces.
* Indent all the source code using Emacs.
* Some minimal documentation, at least an overview README file
\.[
preston-werner 2010
\.]
and man pages
\.[
collyer cox
\.]
.

## Rejected alternatives

You could use an integrated environment.
With Emacs and JSON-RPC
(ELisp and ISLisp are not identical but are very similar),
but I reject this because jsonrpc is outside this list and
I don't want to maintain my own.

DbC would be another nice-to-have,
but I settle for `(declare`.

Could do simple multi-user,
using the IRCv3 bots (nickserv, chanserv) and IRCCloud or similar

# Refinement to Production-Quality

First, software at the level of the previous section is quite usable.
It should be confirmed that further improvement is, in fact, required.
If so, I argue that there is a repeatable procedure to improve the quality of a
(reasonably well-written) prototype to a releaseable product.

First, ensure that the surrounding infrastructure is in place:

* Configuration management. The prototype should already have been checked into git.
* Build. Write an ASDF description, and install as a local quicklisp package.
* Test.
  Write FiveAM
  test cases.
* Track. Start using a defect tracking system.

Then, the following code & documentation improvements should be made:

* Document the system more exhaustively
* Can use more of quicklisp, e.g. the trivial-\* libraries.
* Port to platform.sh?

## Documentation Details

Depend only on GFM,
in the same spirit as the software.
The use of tools like
PP and Pandoc is postponed indefinitely.
PlantUML *should* be used where it can replace ad-hoc text.

Documents should be stored under git in a "doc" subdirectory of the project.

I think it is a good idea to keep the separation between library and UI code
when using ltk.

### Library

This was the subject of
\.[
bane 2008
\.]
. The output artifacts are a module guide an set of module interface specs.
However, some of this documentation is better in the source code:

* The summary of functions should be taken care of by having the public functions and classes commented.
* The formal requirement for function behaviour can be donw with
  tables with Basic English
\.[
basic english
\.].

### UI

The following can be added as sections to the README:

* Uses hierarchy (but at a module level of granularity)
* Task hierarchy

And a proper software requirements spec should be written filling in any blanks that the man pages leave.  
The specification of input and output variables is best left at the level of tables and Basic English again.

*TODO*: For the UI *technology*, is it best to skip local GUIs altogether and go
straight to ParenScript, Backbone, etc.?

## Testing

Unit (FiveAM) tests should be derived from the module interface specs.
Property-based testing would be nice here, but there doesn't seem to be a readily-available library.
System tests should be derived from the requirements spec.
It's ok for system tests to use the same interfaces as the ltk code.
All tests should be automated,
except possibly for the UI/view layer.
Q: These scripts could be generated from a literate test plan?

It would be nice to push some of the testing work "back" in the V model to contracts for the functions,
but quid-pro-quo isn't really blessed.

# Conclusion

A method for developing software from an incomplete understanding of the requirements is given.
It is hoped that this is more effective than most of what is currently-used.
\.[
$LIST$
\.]