diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/breaking_rules.md | 25 |
1 files changed, 7 insertions, 18 deletions
diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md index db4f28c..694261b 100644 --- a/doc/breaking_rules.md +++ b/doc/breaking_rules.md @@ -1,15 +1,12 @@ title: Breaking the Rules: Refining Prototypes Into Products author: Darren Bane -copyright: 2020 Darren Bane, CC BY-SA +copyright: 2020-21 Darren Bane, CC BY-SA # Abstract Recommendations for a process to refine prototypes into production-quality code are made. -*TODO*: Q: re-cast much of this document as Architecture -Decision Records? A: N - # Introduction The conventional wisdom is that prototypes should be discarded once the lessons @@ -19,8 +16,6 @@ In the spirit of [1] I argue that improvements in development tools have invalidated this. -*TODO*: case study - # Previous Work There is a long history of recommending prototyping as a way to construct @@ -54,9 +49,7 @@ without earning money. ## Design Decisions -The programming language chosen is a particular style of Common Lisp. -For readability my -[ISLisp-like subset of CL](bane.20.cdr15.md) should be followed where practical[5]. +The programming language chosen is ISLisp. Reasons for this decision include: * Contrary to a lot of other languages, Lisp is fairly paradigm-agnostic. @@ -64,13 +57,10 @@ Reasons for this decision include: * The imperative and object-oriented paradigms are commonly taught, used in industry, and have a small "impedence mismatch" to current hardware. -* The existence of quicklisp. - Popularity is not really a reason for choosing Common Lisp over ISLisp, - but slotting into quicklisp *is*. Detailed implementations, libraries, etc. are as follows: -* The SBCL compiler. +* The Easy-ISLisp interpreter/compiler. * Avoid multi-threading at this stage, event-driven should do the job. * Not sure if this is relevant for a prototype, but you could do simple multi-user @@ -84,19 +74,18 @@ it could be difficult to satisfy expectations. ### Dependencies For the prototyping phase, -you should *really* limit yourself to the ISLisp subset. +you should *really* limit yourself to ISLisp. If absolutely necessary you can choose some of the libraries mentioned in the "Productisation" section below. ## 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. +* Divide the system into "packages". This can start from just "section headers" with lots of semicolons. -* Write docstrings for at least each public fun, class and package. +* Write comments for at least each public fun, class and package. There are good guidelines in the Elisp manual, but for now one sentence will suffice. -* Use `declare` +* Use `assure` or `the` to check the types of parameters in public interfaces (see below). * Indent all the source code using Emacs. * Some minimal documentation, at least an overview like in [README driven development](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) |