Examples:
> 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.
A value is an expression? what is a Clojure 'expression'? Why should it be called a 'form'? If it is arbitrary, why not call it 'expression'? What does it mean to 'take an expression'? What is 'many'? A macro, the variadic parameterS, which should be called 'body'? The macro has more than one variadic parameter and they all should be called 'body'?
> These defaults derive from the idioms of the Clojure ecosystem and common sense.
'Common sense'? What?
> 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.
What is a value? what is 'anything'? The next sentence talks about 'objects'. Is 'anything' always an object? Why don't we talk about 'any object', instead of 'anything'? What does the number of possible actions have to do how 'rare' a name is?
> 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.
A data type is 'represented' by a map? What does that even mean? 'Anything'? What is 'anything' in this context and what means 'entry' in this context?
This goes on and on.
> At runtime, our scope is any data we can see from within our thread.
What is this 'we' at runtime and what does it mean for 'we' to 'see' data?
> Conversely, we can think of sending an HTTP request as sailing across an ocean; any transfer of data, pushed or pulled, requires effort.
What?
> 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.
What does it mean for a function to cross scope boundaries? What is a scope boundary?
> There are two kinds of macros: those which we understand syntactically, and those which we understand semantically.
There are two kinds of macros, those who begin with WITH and those who do not. What does it mean to 'understand syntactically'/'semantically'?
> To use with-open effectively, we must macroexpand it in our heads whenever it appears in the code.
what?
> syntactic macros
What is that exactly?
> Transforming arbitrary code is difficult and sometimes impossible
What?
Macros: ... > Readers must not only understand the semantics of the transformation, but also its exceptions and failure modes.
Personally I, as a reader, am more interested in the semantics of the generated code.
> macroexpanded syntax
How can I macroexpand syntax?
> Naming is a problem which cannot be solved, but also cannot be ignored.
What kind of problem is it and why can't it be solved. But then I can not ignore it? It can't be solved, but I can not ignore it?
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<->code.
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/described.