
Common Lisp Style Guide - ska80
https://lisp-lang.org/style-guide/
======
Jach
Also worth mentioning is Peter Norvig's and Kent Pitman's style guide. It's
got a bunch of examples but I've found the presentation helpful when thinking
about style in general for other languages, too:
[https://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-
style.pdf](https://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-style.pdf)

The code in Norvig's book "Paradigms of Artificial Intelligence Programming"
is enjoyable to read as well. As a pdf the book itself is freely available:
[https://github.com/norvig/paip-lisp](https://github.com/norvig/paip-lisp)

And then of course there's the classic Costanza guide at
[http://www.p-cos.net/lisp/guide.html](http://www.p-cos.net/lisp/guide.html)
(not so much about style per se) that contains an important remark, "There
cannot be "the one definitive guide" to Lisp. What I present here is what I
would have liked to have seen in the first place. Other people probably prefer
a different approach."

A quick glance at the broader open source ecosystem will show anyone that most
projects don't follow this particular style guide, or this guide is silent on
certain things that are probably considered good form enough to put in a
company guide, like using uninterned symbols for packages, or using qlot for
version pinning your dependencies and having reproducible builds in your CI
system, or using UIOP for anything to do with file paths, or... One needs to
get comfortable loading a system and then using the usual cross-referencing
features of an editor (emacs, vim, atom
([https://atom.io/packages/slima](https://atom.io/packages/slima)), really
anything that can talk to a swank server...) since reading code will be the
surest way to understand it, especially when it might not be laid out as you
expect.

------
stereolambda
Contrary to a sibling, I think that Common Lisp very much needs style guides.
Maybe not one, but some for various use cases. The standard library feels like
a sprawling jungle and the Rambo-style idiosyncratic programming syndrome in
the ecosystem doesn't help. Like how do you fill a hash table idiomatically,
or manipulate strings. On the other hand, the merits of the language itself
keep me going back to it.

In my projects I often find myself wishing for some actually comprehensive and
written down guide to maintain consistency and elegance. It's hard to do it
entirely in your head. I mean, even a multitude of these would be fine if
they'd be explicit and followed. Let's build roads through this wilderness.
One day I'll get around to (also) doing it myself ;p

The OP is quite short, but the Google guide they cite and some ones linked by
others here seem interesting.

One thing I'd like sorted is naming CLOS writers and accessors as opposed to
readers. I feels that it should be somehow communicated what they are.

------
mapcars
One thing which Common Lisp needs the least today is the style guide :)

I'd love to see more apps, innovations, success stories and use cases.

~~~
umvi
I think Common Lisp just needs a rebranding/remarketing strategy. Until
recently I always thought it was an ancient, mostly obsolete language that had
a cult following due to Emacs or something. For some reason I grouped Common
Lisp together with Fortran and COBOL in my mind and didn't realize it was
separate from Lisp.

That perception needs to change if you want it to gain more traction among
developers.

~~~
cageface
S-expr syntax will doom the lisp family to niche applications. I really didn’t
want to accept this for a long time because I think lisp is a beautiful
language but I finally gave up on it.

~~~
justinmeiners
syntax is the deciding factor in a languages success?

~~~
owl57
JS seems even more popular than warranted by its place in the browser. Maybe
Netscape management wasn't completely off target with that "Make it look like
Java" thing.

------
metroholografix
I find that the first two points (Use Libraries and Write Libraries) in the
way they’re presented conflict with each other and they also go against my
personal experience, at least when it comes to robust code.

First, using libraries is great but it always comes at a cost so that I’m
always performing a cost-benefit analysis before I choose a third party
library. The best case is that the library is well-written, well-documented
and close to authoritative, meaning it attempts to maximally cover the problem
domain (and not just solve small parts of the domain, typically those parts
that scratch the itches of the developer). A lot of libraries out there are
far from the best case. Most Common Lisp libraries out there are very far from
best case.

Second, writing libraries or as the CL Style Guide puts it: “In short: write
many small libraries (and I’ll add here the implied when solving a specific
problem).” This sounds nice in theory but I find that it often falls apart in
practice. Most developers that set out to solve a problem are focused on the
problem and it’s hard to get them to decompose that problem into libraries
that are best-case. Far more typically, if they do end up decomposing the
problem into libraries, they will do so in haste and will only do the minimum.
Or they may not yet possess sufficient understanding of the domain that would
let them write a “best-case” library. This leads to a proliferation of
libraries with similar functionality, with no clear “winner”. No clear “best-
case” library for others to use.

Thus we see the conflict between the two statements. I would reword them as
such:

\+ Use third party libraries but perform a cost-benefit analysis before doing
so.

\+ Only write libraries (meant for others to reuse) if you are willing to put
in the best-case effort. If you are writing such a library, then do attempt to
minimize third party dependencies. It makes it a lot easier for others to do a
cost-benefit analysis and also more probable that your library will end up
used. Choose best-case libraries to depend on.

The things we’re trying to avoid are duplication of effort, expansion of the
library space with similar libraries - no standouts - that end up confusing
newcomers and dependency hell where it becomes expensive to do a cost-benefit
analysis.

~~~
nerdponx
_Only write libraries (meant for others to reuse)_

That might be the missing distinction here. Avoid writing monolithic projects;
you aren't going to turn every sub-module into a standalone library for other
people to use, but the modularity will help you and your project anyway, and
then you or someone else _could_ spin off your code if they wanted to.

------
geokon
one thing I haven't found a solution for is how to make Lisp/Clojure play nice
with version control and diffs

you take something like this

    
    
        (defpackage my-package 
          (:use :cl) 
          (:import-from :alexandria 
                        :with-gensyms 
                        :curry))
    

and you want to add an item to the list.. so you need to change the :curry))
line to be :curry and then add a new item. anyone have a workaround?

Of course if you had a lisp with no parans then you'd never have this problem
to start with...

    
    
        defpackage my-package 
          :use :cl
          :import-from :alexandria 
                       :with-gensyms 
                       :curry
                       :new-thingy
    

"Indentation is two lines per form"

Emacs seems to always do one space for Elisp and Clojure and two spaces for
'let' and 'if' forms. or did I screw something up in my init file?

~~~
IronBacon
I would add it at the beginning of the list instead of the end, if the list
order wasn't important. I wouldn't put premptively the closing parens on a
line alone tho.

~~~
malloryerik
Just out of curiosity, why not put the closing parens on their own line in the
case of some rare instance when this improves functionality?

~~~
IronBacon
Probably because I learned to never put them on their own and now, when I see
them, I found them somewhat awkward.

------
arethuza
It's been a long time since I used common lisp, but I seem to remember that
the convention was to use _if_ in a conditional expression and _when_ for
something that conditionally produces a side effect?

~~~
diggan
If it's anything like Clojure (big assumption, but skimming the submission
link seems to confirm things are the same), `if` is used when you want to do
something OR do something else. You use `when` only when there is no `OR do
something else` and/or when there is multiple things you want to do inside.

~~~
pvinis
It's interesting to see how you use your if and when in your sentences.
Surprisingly, you have an if without an else, and a when with an or at the
end! :p

I do remember that convention though, and it makes sense. I just found your
usages in text interesting.

~~~
diggan
Haha, you're right! Re-reading my own comment, I seem to switch context
between "normal language" conditionals where the rules obviously are different
from the "programming language" context where they are strictly defined.

Fun observation :)

------
ghettoimp
Hrmn. I don't think I've ever seen Lisp code where both branches of an IF are
indented the same amount...

~~~
reikonomusha
It’s standard with Emacs and SLIME.

------
d--b
I am surprised that the style guide is not written in Lisp. It's very un-
lispy.

