[Raynes]

This is a very brief and subjective style guide (more like general recommendation) for writing Lisp code. I'll use Clojure in my examples, because it's what I'm most familiar with, but I'll try to be Lisp-agnostic.

A lot of people are inclined to put closing parens on their own line, like this:

(defn func [] 
  (dostuff (more-stuff)
  )
)

or similar. This is poor style, and you would be better off stacking the closing parens on the end. If you find it difficult to tell which opening paren matches the closing paren you're looking at, your editor probably (or certainly should) has a "highlight-matching-parenthesis" function or something similar that will highlight the paren that matches the one the cursor is over. If it doesn't I strongly encourage you to use one that does.

The standard indentation for Lisp code is two spaces unless you are lining up function arguments.

(defn blah []
  (dostuff
    first-arg
    second-arg)
  (more-stuff first-arg second-arg))

Knowing when to newline and indent is an acquired skill. You should keep your lines under 80 characters at max.

Don't over comment your code. Comments are great, but you should favor using docstrings instead when possible, and saving comments for explaining really cryptic lines that you don't think would be easily followed by Lisper who is reading your code.

(defn blah
  "This function doesn't do much of anything"
  [] (donothing))

Also, try to avoid using too much whitespace. Lisp code should be terse without random garbage in between lines. Try to keep the number of empty lines between definitions at 1 non-comment line. Anymore is usually just unnecessary, leaning more toward unreadability than not.

The conventions for function names are different for each Lisp. Some (Clojure) end predicate functions (functions that return true or false) with a question mark. Some end these with a 'p'. The constant between Lisps is don't be afraid to use longer function names than you're used too. make-my-day-punk isn't necessarily a bad name if it is highly descriptive of what the function actually does. Also, always separate words in a function name with a hyphen (-).


Well, that's about it. Lisp is a language with very little syntax. There isn't much to styling your code. I highly encourage you to use an editor that can do proper Lisp indentation and parenthesis highlighting. If you don't use an editor with at least parenthesis matching, you're going be hurting pretty bad pretty quick. The parentheses are important to Lisp's power, but without a decent editor, it can become a little difficult to figure out what paren matches what. Proper indentation, knowing when to newline, and keeping function definitions small can alleviate this quite a bit, but it still helps to have paren matching.

Happy Lisp Hacking!

This post has been edited by Raynes: 21 July 2010 - 11:22 PM

[jon.kiparsky]

Raynes, on 21 July 2010 - 04:00 AM, said:

This is a very brief and subjective style guide (more like general recommendation) for writing Lisp code. I'll use Clojure in my examples, because it's what I'm most familiar with, but I'll try to be Lisp-agnostic.

A lot of people are inclined to put closing parens on their own line, like this:

(defn func [] 
  (dostuff (more-stuff)
  )
)

or similar. This is poor style, and you would be better off stacking the closing parens on the end. If you find it difficult to tell which opening paren matches the closing paren you're looking at, your editor probably (or certainly should) has a "highlight-matching-parenthesis" function or something similar that will highlight the paren that matches the one the cursor is over. If it doesn't I strongly encourage you to use one that does.

(... good advice snipped ...)
Well, that's about it. Lisp is a language with very little syntax. There isn't much to styling your code. I highly encourage you to use an editor that can do proper Lisp indentation and parenthesis highlighting. If you don't use an editor with at least parenthesis matching, you're going be hurting pretty bad pretty quick. The parentheses are important to Lisp's power, but without a decent editor, it can become a little difficult to figure out what paren matches what. Proper indentation, knowing when to newline, and keeping function definitions small can alleviate this quite a bit, but it still helps to have paren matching.

Happy Lisp Hacking!

This is exactly why I tell beginning programmers to stay away from crutches (including paren-matching, syntax highlighting, auto-complete, and all the other steam-powered gimgrackery) until they can write a serious (non-trivial) application without it. As long as you're writing your student code, the arguments about increased productivity are irrelevant, what you need to do is learn the craft. The craft of lisp includes looking at a well-styled piece of code and seeing how it's put together, and seeing where it's wrong, if it is. You get that by writing the code for yourself and matching the parens by eye. If you write your lisp in vanilla vi, you will get that sixth sense for parentheses. If someone (or something) does your matching for you, you won't need it, so you won't have it.

I'm not opposed to using tools like specialized editors, of course, but I think they hinder development of necessary skills if deployed too soon. There's no need for paren-matching when you're working your way through The Little Schemer.

[Raynes]

Sure, in a perfect world.

In our imperfect world, a lot of people jump into a Lisp and then run away screaming because of the parentheses. Using an editor that can help you match them alleviates the problem very painlessly. I'd much rather people start out using an editor that can match parens instead of running away screaming because the parens confuse them. Therefore, I have to disagree and continue recommending parentheses matching editors/editor plugins.

[jon.kiparsky]

Fair enough. I don't really mind if people run away screaming. I figure if they can't get their heads around the language, they probably aren't ready for it yet. The constructs of the language mirror the complexity of the ideas - someone who can't hold the nesting of parentheses in their head probably can't hold the nesting of the functions, either, and they just won't understand what they're doing.
But it's not a religious thing for me - if a beginner really thinks he wants to use paren matching, I won't despise him for it. More pity than scorn, that's what I've got.