diff options
Diffstat (limited to 'doc/breaking_rules.md')
| -rw-r--r-- | doc/breaking_rules.md | 73 |
1 files changed, 22 insertions, 51 deletions
diff --git a/doc/breaking_rules.md b/doc/breaking_rules.md index b8887b3..5c622f8 100644 --- a/doc/breaking_rules.md +++ b/doc/breaking_rules.md @@ -6,9 +6,6 @@ copyright: 2020 Darren Bane, CC BY-SA Recommendations for a process to refine prototypes into production-quality code are made. -\.R1 -accumulate -\.R2 *TODO*: Q: re-cast much of this document as Architecture Decision Records? A: N @@ -18,10 +15,7 @@ Decision Records? A: N The conventional wisdom is that prototypes should be discarded once the lessons have been learned, and the final product written again from scratch. -In the spirit of -\.[ -beck 1999 -\.] +In the spirit of [1] I argue that improvements in development tools have invalidated this. @@ -31,15 +25,8 @@ invalidated this. There is a long history of recommending prototyping as a way to construct systems. -I would personally recommend -\.[ -robertson agust\(i 1999 -\.] -and -\.[ -pitman 1994 -\.] -. +I would personally recommend [2] +and [3]. *NB*: I am almost certainly re-inventing a SmallTalk wheel. However I argue that Lisp's combination of imperative & OO @@ -59,15 +46,8 @@ arguing that it is possible to *refine* a prototype into a product. The first step is to construct a prototype, or in modern terminology a "Minimal Viable Product". -These recommendations follow on from -\.[ -robertson agust\(i 1999 -\.] -and -\.[ -bane 2008 -\.] -. +These recommendations follow on from [2] +and [4]. Reasons for choosing Common Lisp include: @@ -82,11 +62,7 @@ Reasons for choosing Common Lisp include: * Contrary to a lot of other languages, it is fairly paradigm-agnostic. At the same time, I want a clean subset of CL, -so cleave as close to ISLisp as practical -\.[ -bane 2020 -\.] -. +so cleave as close to ISLisp as practical[5]. It was decided to use the imperative/object-oriented paradigm, partly for familiarity in industry and @@ -112,15 +88,8 @@ Even though this is a prototype, attention should be paid to basic craftsmanship * Use `declare` to check the types of parameters in public interfaces. * Indent all the source code using Emacs. -* Some minimal documentation, at least an overview README file -\.[ -preston-werner 2010 -\.] -and man (actually, mdoc) pages -\.[ -dzonsons -\.] -. +* Some minimal documentation, at least an overview README file[6] +and man (actually, mdoc) 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. If there is no standard protocol, I recommend using JSON-RPC as a base and following the documentation style of LSP. @@ -205,19 +174,13 @@ The specification of input and output variables is best left at the level of tab ### Library -This was the subject of -\.[ -bane 2008 -\.] -. The output artifacts are a module guide an set of module interface specs. +This was the subject of [4]. +The output artifacts are a module guide an set of module interface specs. However, some of this documentation is better in the source code: * The summary of functions should be taken care of by having the public functions and classes commented. * The formal requirement for function behaviour can be done with - tables with Basic English -\.[ -basic english -\.]. + tables with Basic English[8]. * Although full design-by-contract may be out of reach a poor-man's version can be used with public functions following a pattern. This can also do some of the formal requirements. @@ -275,6 +238,14 @@ following the pattern above. A method for developing software from an incomplete understanding of the requirements is given. It is hoped that this is more effective than most of what is currently-used. -\.[ -$LIST$ -\.] + +# References + +[1]Kent Beck, Extreme Programming Explained (1999). +[2]David Robertson and Jaume Agustâ–’, Software Blueprints: Lightweight Uses of Logic in Conceptual Modelling, Addison Wesley Longman (1999). +[3]Kent Pitman, Accelerating Hindsight: Lisp as a Vehicle for Rapid Prototyping (1994). +[4]Darren Bane, Design and Documentation of the Kernel of a Set of Tools for Working With Tabular Mathematical Expressions, University of Limerick, Ireland (19 Jul 2008). +[5]Darren Bane, An ISLisp-like subset of ANSI Common Lisp, Ireland (21 Aug 2020). +[6]Tom Preston-Werner, Readme Driven Development, San Francisco, CA, USA (23 Aug 2010). available: https://tom.preston-werner.com/2010/08/23/readme- driven-development.html [accessed 27 May 2020]. +[7]Kristaps Dzonsons, Practical UNIX Manuals. available: https://manpages.bsd.lv/toc.html [accessed 9 Oct 2020]. +[8]"Basic English" in Wikipedia. available: https://en.wikipedia.org/wiki/Basic_English [accessed 28 May 2020]. |