6 ms·

Common Lisp Style Guide

114 points by ska80 7y ago

metroholografix 7y ago
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 7y ago
  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.
- mark_l_watson 7y ago
  This is just a suggestion based on how I work: I have a private git repo common-lisp that contains all of my personal CL code and I make this a root for finding libraries with Quicklisp. As the style guide suggests, I break up my large CL projects into many small libraries that are subdirectories in this repo that I use alongside other people’s libraries in Quicklisp. EDIT: to be more clear, my single git repo contains as subdirectories all libraries I write as well as all applications I write that use my libraries and other people’s libraries in Quicklisp. I almost always provide Makefile files to create standalone applications for each non-library I write so I don’t have to run code in a repl unless I am developing.
arethuza 7y ago
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 7y ago
  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 7y ago
    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 7y ago
      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 :)
- aidenn0 7y ago
  When has no else and if has no explicit progn. If you need an else for a side effect then cond or if will be used. I don't think there is a consensus on which of those to use for side effect vs expression when an else is needed
  - arethuza 7y ago
    I probably got that idea from CLtL: https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node84.html https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node84.html Very much a "stylistic preference" though! Edit: I realised that for the 6 years or so I wrote CL as part of my day job that my well thumbed copy of CLtL was by far the most referenced programming language book I have ever used (mostly falling open at either the loop or CLOS chapters). Not sure what this says about CL!
Jach 7y ago
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.
mapcars 7y ago
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 7y ago
  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 7y ago
    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 7y ago
      syntax is the deciding factor in a languages success?
      - owl57 7y ago
        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.
      - cageface 7y ago
        It can be if it’s off putting enough to the average developer. There were a lot of good ideas in lisp. Just about all of them have made their way into popular languages except the syntax. It’s not an accident imo.
      - carapace 7y ago
d--b 7y ago
I am surprised that the style guide is not written in Lisp. It's very un-lispy.
stereolambda 7y ago
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.
ghettoimp 7y ago
Hrmn. I don't think I've ever seen Lisp code where both branches of an IF are indented the same amount...
- reikonomusha 7y ago
  It’s standard with Emacs and SLIME.
geokon 7y ago
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 7y ago
  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.
  - geokon 7y ago
    That would have the same effect of diffing two lines :)
    - IronBacon 7y ago
      Mmh, yeah. Sometimes I lack reading comprehension. So, I would think it's not a thing that can be solved with style guidelines, maybe a different diffing paradigm that handles elements addition or deletion from a list?
  - malloryerik 7y ago
    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?
    - 7y ago

114 points by ska80 7y ago

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 7y ago
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.
mark_l_watson 7y ago
This is just a suggestion based on how I work: I have a private git repo common-lisp that contains all of my personal CL code and I make this a root for finding libraries with Quicklisp. As the style guide suggests, I break up my large CL projects into many small libraries that are subdirectories in this repo that I use alongside other people’s libraries in Quicklisp. EDIT: to be more clear, my single git repo contains as subdirectories all libraries I write as well as all applications I write that use my libraries and other people’s libraries in Quicklisp. I almost always provide Makefile files to create standalone applications for each non-library I write so I don’t have to run code in a repl unless I am developing.

arethuza 7y ago

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 7y ago
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 7y ago
  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 7y ago
    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 :)
aidenn0 7y ago
When has no else and if has no explicit progn. If you need an else for a side effect then cond or if will be used. I don't think there is a consensus on which of those to use for side effect vs expression when an else is needed
- arethuza 7y ago
  I probably got that idea from CLtL: https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node84.html https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node84.html Very much a "stylistic preference" though! Edit: I realised that for the 6 years or so I wrote CL as part of my day job that my well thumbed copy of CLtL was by far the most referenced programming language book I have ever used (mostly falling open at either the loop or CLOS chapters). Not sure what this says about CL!

Jach 7y ago

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.

mapcars 7y ago

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 7y ago
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 7y ago
  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 7y ago
    syntax is the deciding factor in a languages success?
    - owl57 7y ago
      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.
    - cageface 7y ago
      It can be if it’s off putting enough to the average developer. There were a lot of good ideas in lisp. Just about all of them have made their way into popular languages except the syntax. It’s not an accident imo.
    - carapace 7y ago

d--b 7y ago

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

stereolambda 7y ago

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.

ghettoimp 7y ago

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

reikonomusha 7y ago
It’s standard with Emacs and SLIME.

geokon 7y ago

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 7y ago
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.
- geokon 7y ago
  That would have the same effect of diffing two lines :)
  - IronBacon 7y ago
    Mmh, yeah. Sometimes I lack reading comprehension. So, I would think it's not a thing that can be solved with style guidelines, maybe a different diffing paradigm that handles elements addition or deletion from a list?
- malloryerik 7y ago
  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?
  - 7y ago