Tutorial on Good Lisp Programming Style (1993) [pdf]

https://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-style.pdf

by kbp • 9 years ago

7 1 9 years ago

cs.umd.edu

kbp• 9 years ago

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.

Tutorial on Good Lisp Programming Style (1993) [pdf]

Related Stories