
Tutorial on Good Lisp Programming Style (1993) [pdf] - kbp
https://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-style.pdf
======
kbp
This guide is great; most of it is just as applicable to programming in
general as it is to Lisp. One thing that stands out to me as a good way of
phrasing something is "Documentation strings are better than comments." Even
in something like Java with Javadoc instead of docstrings, the same advice
applies: in properly factored code, most explanations should be tagged onto a
function or variable in a standard way like that to explain its purpose; if
you have to explain something inline, not as an interface but only to people
reading that section of code, it's a sign that maybe you haven't factored your
code enough. Like the quote it provides from Kernighan and Plauger says: Don't
comment bad code--rewrite it.

Another line I like: Documentation should be organized around tasks the user
needs to do, not around what your program happens to provide. Adding
documentation strings to each function usually doesn't tell the reader how to
use your program, but hints in the right place can be very effective.

