From 3e547ec218830ff391859287e404a19775aa37a1 Mon Sep 17 00:00:00 2001 From: Darren Bane Date: Tue, 20 Apr 2021 15:47:49 +0100 Subject: Doc updates --- cap-muck.lsp | 13 +++---------- doc/breaking_rules.md | 25 +++++++------------------ 2 files changed, 10 insertions(+), 28 deletions(-) diff --git a/cap-muck.lsp b/cap-muck.lsp index fd90626..8cace16 100644 --- a/cap-muck.lsp +++ b/cap-muck.lsp @@ -1,9 +1,3 @@ -(defpackage #:cap-muck - (:use #:openlisp) - (:export - #:main) - ) -(in-package #:cap-muck) (defglobal *terminate-program* nil) (defconstant +bold+ "#\esc[1m") @@ -109,9 +103,7 @@ ()) ;; TODO: Use the reader, for prototype at least? -;; Can switch to postmodern for production. -;; -;; Or dbm? +;; Or dbm? (Espcially for production.) (defun read-room-database () (setq *rooms* '()) (with-open-input-file (file +rdb+) @@ -180,4 +172,5 @@ (read-room-database) (while (not *terminate-program*) (check-for-inputs))) -(provide "cap-muck") +(main) + 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) -- cgit 1.4.1-2-gfad0