A few brief guidelines about the coding style for the Sheeple source
You are highly encouraged to make contributions to the Sheeple Manual, maintained in GNU Texinfo format here. Please follow these guidelines:
Wrap text to 80 columns
This is not Common Lisp, so there’s no need for a line to go further than 80 columns. This is only for text, though; Texinfo commands (particularly, @node definitions) should go as far as necessary to keep them on one line.
Use the index
Every index entry is useful. Use separate indices for clarity; if there are
too many indices at the end, merge some together, but keep the entries
within the source separate. For example,
STANDARD-SHEEP is both a concept
and a variable, and should thus be indexed (at least) twice. At the end of
the document, the variable index can be merged with the function index, so
that we don’t have fifty different half-page indices.
Remarkable as it may seem, there’s even less TeX talent among the Sheeple developers than there is Common Lisp talent, so please stick to the Texinfo commands, and use them idiomatically, so that we can understand your code. If you are a TeX wizard, let us know, and maybe you can become Sheeple’s official documentarian. Otherwise… Keep It Simple, Stupid!
Document your code, even if it is not exposed to the user. A well-documented function devoid of comments is better than an undocumented function with several short comments in its body.
Describe WHAT, not HOW
Supply an API through docstrings. If a function’s algorithm is complex, don’t describe it in the docstring; either use comments, or simplify the algorithm.
Comment your code as described in CLHS 18.104.22.168. Occasionally, when large blocks of code must be commented out, it is alright to use whatever mass-commenting your editor provides, but try to stick to these conventions for “permanent” comments.
If a comment is your opinion, rather than a clarification of the code, please make clear that you left that comment. For example: ;;; This function conses too much. - John Foo
Indentation & Wrapping
Standard CL indentation
SLIME is a fairly good guide here, although it does mess up some forms, such as definitions of qualified replies. Indent these forms by hand.
Wrap lines below 100 columns
In general, aim for a balance between readability and convenience. CL nests a lot, and the MOP identifiers have long names, so it’s hard to keep complex definitions wrapped to 70 or 80 columns. Each file has a row of 100 semicolons at the end of its header, that can provide a quick reference.