Elements of Clojure
I fear this reads not very precise, mostly arbitrary and random.<p>Examples:<p>&gt; If a value is an arbitrary Clojure expression, it should be called form. If a macro takes many expressions, the variadic parameters should be called body.<p>A value is an expression? what is a Clojure &#x27;expression&#x27;? Why should it be called a &#x27;form&#x27;? If it is arbitrary, why not call it &#x27;expression&#x27;? What does it mean to &#x27;take an expression&#x27;? What is &#x27;many&#x27;? A macro, the variadic parameterS, which should be called &#x27;body&#x27;? The macro has more than one variadic parameter and they all should be called &#x27;body&#x27;?<p>&gt; These defaults derive from the idioms of the Clojure ecosystem and common sense.<p>&#x27;Common sense&#x27;? What?<p>&gt; If a value can be anything, we should call it x. This is fairly rare, as usually the only things we can do with an object involve =, hash, and str.<p>What is a value? what is &#x27;anything&#x27;? The next sentence talks about &#x27;objects&#x27;. Is &#x27;anything&#x27; always an object? Why don&#x27;t we talk about &#x27;any object&#x27;, instead of &#x27;anything&#x27;? What does the number of possible actions have to do how &#x27;rare&#x27; a name is?<p>&gt; Let’s consider a student datatype, which is represented as a map whose keys and values are well defined, either using documentation or a formal schema. Anything called student should have at least these entries, and sometimes only these entries.<p>A data type is &#x27;represented&#x27; by a map? What does that even mean? &#x27;Anything&#x27;? What is &#x27;anything&#x27; in this context and what means &#x27;entry&#x27; in this context?<p>This goes on and on.<p>&gt; At runtime, our scope is any data we can see from within our thread.<p>What is this &#x27;we&#x27; at runtime and what does it mean for &#x27;we&#x27; to &#x27;see&#x27; data?<p>&gt; Conversely, we can think of sending an HTTP request as sailing across an ocean; any transfer of data, pushed or pulled, requires effort.<p>What?<p>&gt; If a function crosses scope boundaries, there should be a verb in the name. If it pulls data, it should describe the datatype it returns.<p>What does it mean for a function to cross scope boundaries? What is a scope boundary?<p>&gt; There are two kinds of macros: those which we understand syntactically, and those which we understand semantically.<p>There are two kinds of macros, those who begin with WITH and those who do not. What does it mean to &#x27;understand syntactically&#x27;&#x2F;&#x27;semantically&#x27;?<p>&gt; To use with-open effectively, we must macroexpand it in our heads whenever it appears in the code.<p>what?<p>&gt; syntactic macros<p>What is that exactly?<p>&gt; Transforming arbitrary code is difficult and sometimes impossible<p>What?<p>Macros: ...
&gt; Readers must not only understand the semantics of the transformation, but also its exceptions and failure modes.<p>Personally I, as a reader, am more interested in the semantics of the generated code.<p>&gt; macroexpanded syntax<p>How can I macroexpand syntax?<p>&gt; Naming is a problem which cannot be solved, but also cannot be ignored.<p>What kind of problem is it and why can&#x27;t it be solved. But then I can not ignore it? It can&#x27;t be solved, but I can not ignore it?<p>Worse: much of the advice assumes a static text program where the only option I have is to read the text. Not a Lisp system with data&lt;-&gt;code.<p>Probably also a good idea to write a glossary, where the basic terms (form, value, expression, scope, scope boundary, data, parameter, argument, variadic argument, syntactic macro, failure mode, ...) are defined&#x2F;described.