aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorDarren Bane <dbane@tilde.institute>2021-04-20 15:47:49 +0100
committerDarren Bane <dbane@tilde.institute>2021-04-20 15:47:49 +0100
commit3e547ec218830ff391859287e404a19775aa37a1 (patch)
tree58be6ae265d4c556a28ec81381c516809d884c44 /doc
parenta964f55b4b983b6b286ad61c02cfce819977e6bf (diff)
downloadlsp-3e547ec218830ff391859287e404a19775aa37a1.tar.gz
Doc updates
Diffstat (limited to 'doc')
-rw-r--r--doc/breaking_rules.md25
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)