Show HN: A Guide to Formatting Lisp

There is no ambiguity. When you're researching what some Lisp word does, it is very clear from the nested parentheses in the code which parts of the program are direct arguments of that word, which parts are nested in those arguments, and which are entirely outside of that call to the word.

So if the documentation says that the word's third argument has such and such a meaning, you can easily see in the program which expression corresponds to that argument. You know where that expression begins and ends, and that nothing else is part of the third argument.

The trick is that you must begin on the outside and work your way in, because the meaning of any expression depends on what it is enclosed in. Because of the uniform syntax, there are sometimes elements in an expression which look like forms being evaluated, but are in fact only fragments of the surrounding expression. So there is a difficulty in reading Lisp and it comes from not being able to grok some enclosed X, if you don't know the enclosing Y.

If you don't guess that defclass defines a class, and then ignore it and start reading the interior, then you might wrongly that (defclass a (b c)) is calling somne function called b, with argument c rather than have the correct idea that (b c) are superclasses being inherited by a. You cannot just casually ignore the meaning of a form that you don't know, and just read its interior naively. This is the difficulty in reading Lisp: not having the vocabulary to know what "part of speech" are the constituents of a form, even though its structure is completely unambiguous: you know exactly which parts of the program are the constituents.

The shape of (defclass a (b c)) is exactly the same as that of, say, (setf a (b c)). That shape is informative and helpful, but not with regard to the semantics. The number of expressions which can share this exact shape, yet have entirely different meaning from each other, including the model of evaluation. This is not true in languages that don't have extensible syntax.

Lisp has a lot of unfamiliar vocabulary: destructuring-bind, with-slots, rplacd, block, lambda, unwind-protect, ... and without knowing some vocabulary item which appears in code, you can't properly read it. If you ignore something that you don't know and make a guess about how to read its interior, that can turn out to be spectacularly wrong.