diff options
| -rw-r--r-- | cbasic.lisp | 1 | ||||
| -rw-r--r-- | doc/bane.20.cdr15.md | 3 | ||||
| -rw-r--r-- | doc/breaking_rules.md | 33 | ||||
| -rw-r--r-- | doc/refs | 4 |
4 files changed, 37 insertions, 4 deletions
diff --git a/cbasic.lisp b/cbasic.lisp index 1085e16..5183859 100644 --- a/cbasic.lisp +++ b/cbasic.lisp @@ -22,7 +22,6 @@ ;; ( https://lisp-lang.org/learn/writing-libraries ) (require "cparse") -(require "") (defpackage #:cbasic (:use #:common-lisp) (:export diff --git a/doc/bane.20.cdr15.md b/doc/bane.20.cdr15.md index bb25021..2548c7d 100644 --- a/doc/bane.20.cdr15.md +++ b/doc/bane.20.cdr15.md @@ -36,6 +36,9 @@ ISLisp doesn't have the following features (and probably many more): * structs. Use classes instead. * `print-object`. But you can define it yourself. +CL doesn't have the `*-dynamic` functions, +it's probably best to avoid dynamic scoping anyway. + ## Extensions to ISLisp It was noted in the ISLisp standard document that the committee would have liked to define packages. diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md index 70bcb56..b8887b3 100644 --- a/doc/breaking_rules.md +++ b/doc/breaking_rules.md @@ -10,6 +10,9 @@ are made. accumulate \.R2 +*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 @@ -113,11 +116,15 @@ Even though this is a prototype, attention should be paid to basic craftsmanship \.[ preston-werner 2010 \.] -and man pages +and man (actually, mdoc) pages \.[ -collyer cox +dzonsons \.] . +* Certain parts of a system justify greater detail for a *complete* specification. + These are (newly-designed) network protocols and complex persistent data models. + If there is no standard protocol, I recommend using JSON-RPC as a base and following the documentation style of LSP. + The data models should be documented as commented SQL DDL. ### Run-time type-checking @@ -168,7 +175,7 @@ Then, the following code & documentation improvements should be made: Since we have a working prototype, it may make sense to write the documentation (and contracts, and tests) "bottom-up": -1. Contracts +1. Contracts, static analysis 2. Test cases 3. Module interface specs 4. Module guide, uses hierarchy @@ -224,6 +231,8 @@ basic english (the fixnum res))) ``` +`lisp-critic` can be used to perform static analysis of the codebase. + ### UI ltk is great for local GUIs. @@ -231,6 +240,24 @@ However, a product may require HTMX and the platform.sh stack. Note that I prefer HTMX & ReST (following Fielding) to single-page applications (outside the very specific case of drawing on a canvas using ParenScript). +## Dependencies + +For the prototyping phase, +you should *really* limit yourself to the ISLisp subset. +For productisation you may want to make more of an effort, +but I would still recommend limiting to the following, +in order of preference. +The language/library split isn't as clear in CL as in some other languages, +but use your judgement. + +* For "language" functionality, "[Portability layers](http://portability.cl/)" from that list +* For "library" functionality, any "stars" from the [Awesome-CL](https://github.com/CodyReichert/awesome-cl) list +* Any of the `trivial-` libraries from that list. These may be *forked* and maintained locally. +* Any other `trivial-` libraries available in Quicklisp. +* Other libraries available in Quicklisp. + +The `trivial-` libraries may be *forked* and maintained locally. + ## Testing Unit (FiveAM) tests grow in parallel with the module interface specs. diff --git a/doc/refs b/doc/refs index d380cf2..7fb0ad2 100644 --- a/doc/refs +++ b/doc/refs @@ -1025,6 +1025,10 @@ %T How to Write a Plan 9 Manual Page %O available: http://www.vitanuova.com/inferno/papers/manhow.pdf [accessed 27 May 2020] +%A Kristaps Dzonsons +%T Practical UNIX Manuals +%O available: https://manpages.bsd.lv/toc.html [accessed 9 Oct 2020] + %T Basic English %B Wikipedia %O available: https://en.wikipedia.org/wiki/Basic_English [accessed 28 May 2020] |