diff options
Diffstat (limited to 'doc/breaking_rules.md')
| -rw-r--r-- | doc/breaking_rules.md | 15 |
1 files changed, 8 insertions, 7 deletions
diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md index 29f20d1..0c34594 100644 --- a/doc/breaking_rules.md +++ b/doc/breaking_rules.md @@ -55,8 +55,8 @@ without earning money. ## Design Decisions The programming language chosen is a particular style of Common Lisp. -A clean subset of CL is desired, -so cleave as [close to ISLisp](bane.20.cdr15.md) as practical[5]. +For readability my +[ISLisp-like subset of CL](bane.20.cdr15.md) should be followed where practical[5]. Reasons for this decision include: * Contrary to a lot of other languages, Lisp is fairly paradigm-agnostic. @@ -92,7 +92,7 @@ Even though this is a prototype, attention should be paid to basic craftsmanship * Use `declare` 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 [README](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) file +* Some minimal documentation, at least an overview like in [README driven development](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) and man (actually, [mdoc](https://manpages.bsd.lv/toc.html)) pages[7]. * Certain parts of a system justify greater detail for a *complete* specification. These are (newly-designed) network protocols and complex persistent data models. @@ -150,7 +150,7 @@ it may make sense to write the documentation (and contracts, and tests) "bottom- Depend only on GFM, in the same spirit as the software. The use of tools like -PP and Pandoc should be minised. +nw2md and Pandoc should be minised. PlantUML *should* be used where it can replace ad-hoc text. Documents should be stored under git in a "doc" subdirectory of the project. @@ -189,6 +189,7 @@ However, some of this documentation is better in the source code: ``` `lisp-critic` can be used to perform static analysis of the codebase. +But it's not worth writing custom rules. ### UI @@ -203,8 +204,8 @@ For productisation you may want to add more features. Although the official ANSI standard is moribund, quasi-standard libaries are recommended on the -[awesome list](https://github.com/CodyReichert/awesome-cl), -or [portability layers](http://portability.cl/). +[Awesome-CL list](https://github.com/CodyReichert/awesome-cl), +or [CL portability layers](http://portability.cl/). Usage should be limited as follows, in order of preference. The language/library split isn't as clear in CL as in some other languages, @@ -231,7 +232,7 @@ System tests grow in parallel with 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? A: yes, probably one of the few places to use "PP". +Q: These scripts could be generated from a literate test plan? A: yes, probably one of the few places to use nw2md. As much of the testing work should be pushed "back" in the V model to contracts for the functions, following the pattern above. |