Clojure Cookbook is now accepting contributions | Hacker News Reader

Clojure Cookbook is now accepting contributions

contribute.clojure-cookbook.com

83 pointsrkneufeld27 comments

I'm a clojure newb but I've given it a serious try. The thing I feel most uncomfortable about is the development pipeline and how to debug errors (not necessarily with a debugger). I hope the cookbook has sections for this.

For example, once you get started, I can type my program into the repl piece by piece and copy the working parts into my source file. Or, I can type my code into the source file and evaluate it with the repl. I imagine one choice has more pros/cons than the other.

Emacs... I'm not using it, and I don't know what I'm missing. It seems like the majority of the hardcore clojurists are though and I'd like to know why.

With debugging, I feel like the clojure error messages are not very helpful. I'm pretty sure this is just because I'm new to the language and the programming paradigm. Maybe that can't be taught and just takes time. But I also feel like there are a lot of debugging techniques out there I don't know about.

I've documented my debugging complaints in detail on Stack Overflow here: http://stackoverflow.com/questions/16901836/how-do-i-get-bet...

I learned Clojure + Emacs + Evil-mode + nrepl.el at the same time a few months ago and haven't really changed anything about my workflow since then.

This is how I start Emacs:

    * Open emacs
    * `c-x c-f` to navigate to and open my clj file
    * `c-c m-j` to start nrepl session (opens up in a pane split)
    * `c-w h/j/k/l` to move between windows
    * `m-x find-file-in-project` (I mapped to `;a`) to navigate to 
      other clj files in the git project

And this is my workflow once I have source file and nrepl split-panes open:

    * Edit code
    * `c-x c-e` to eval the expression above cursor
    * `c-c c-k` to eval entire source buffer
    * `m-hyphen c-c c-z` to load source file 
      namespace into nrepl window which I rarely do

I actually rarely use the repl window since you can eval code in the source file.

* I pretty much treat my source file as my repl and use `c-x c-e` to execute the previous form. (Screenshot: http://dl.dropbox.com/u/51836583/Screenshots/l0.png)

* Also, I'll often put the code I'm trying to get to work like `(my-func 1 2 3)` at the bottom of my source file. Then, while I'm hacking on `my-func`'s implementation, I mash `c-c c-k` (eval buffer) which returns the result of the last expression in the file.

* Another nice way to utilize `c-c c-k` is to put your `(assert (= (my-func 1 2 3) 42))` tests right into the source file. The tests will get run every time you eval the buffer. It's a solid test-driven loop baked into the core library!

(See more nrepl keymappings here: https://github.com/kingtim/nrepl.el#keyboard-shortcuts)

I wish I could upvote you more. I've been playing with clojure for weeks and I use nrepl, but it never clicked what a solid workflow could be.

This deserves more upvotes than the 1 that I can give it.

Most Clojureists write code they want to keep in their source file, and then evaluate it by using their editors tooling to send it to the REPL from there. I usually just type things into the REPL for one-off exploration or experimentation.

What editor are you using? Emacs certainly has had the most mindshare so far, but it's a beast to get started with. I recommend CounterClockwise for non-emacs folks: it's got all the features you need to be effective, and has full integration with Leiningen.

As far as errors and error messages; yeah, it's hard, and a lot if it is just getting experience. But one thing that will really help you out is to write your program in very small chunks, and test each part as you go. That way, when something goes wrong, you'll have a very good idea about where to start looking.

Yeah I'm using CCW right now. I like it, but it's annoying that the repl doesn't start with (doc) or (source). I read an article from Stuart Sierra where you can add your own user.clj to the classpath and put code in it to load those up on start, but I haven't tested if CCW's repl will use this correctly. Assuming it does, tips like this are essential and should be in the book IMO.

Your last paragraph is good advice, but IMO I code like that in general. Consider this code:

(-> x doSomething1 doSomething2 doSomething3)

This was tested as I went, but after the fact, I had to change x. Now any part of the whole series of steps could be broken. This is where I spend 15 minutes trying to understand what the error message means. shrug Maybe this is just what's expected when you're new to clojure.

The best advice I can give there is, learn how to read a stacktrace. I won't lie, they're messy, but they do contain the information you need to figure out that sort of problem.

For example, all Clojure function calls have the same sort of appearance in the stacktrace, which you'll learn to recognize. You'll be able to pick out "doSomething2" in the trace, which will then help you narrow in on the problem. Recurse through the stack trace using this technique until you find the specific form which is the problem.

Just added a "reading stacktraces" idea to the book: https://github.com/clojure-cookbook/clojure-cookbook/issues/...

Yeah, I tend to put a `pprint` at various points in the pipeline. (One which returns the form unchanged.)

I use print statements with virtually any programming language, basically using binary search to locate where my assumptions are violated.

You do need to try using Emacs and nrepl. Actually, the best thing would be to watch an experienced lisper work.

It's not just about the REPL and syntax highlighting. You need to see someone use paredit (things like paredit-raise-sexp or paredit-forward-slurp-sexp), evaluate expressions in-place (either seeing the results in the minibuffer or inserting them into the code), use M-. to instantly jump to anything that is defined in the active runtime, etc.

As for debugging, the Clojure experience is pretty bad, compared to (for example) Common Lisp. I'm experienced and use Clojure every day to write large applications, but I still stick to logging for most debug work. And yes, backtraces are horrible.

> Actually, the best thing would be to watch an experienced lisper work

This is what I've been looking for, but I don't know any experienced lispers, which has left me with a huge hill to climb to migrate from CCW to Emacs. Are there any annotated videos (i.e., showing keypresses) available showing lispers at work?

There are a few videos on youtube, but probably best to check out the hack emacs and emacs rocks videos.

Just like Clojure, getting over the intimidation factor of Emacs is 90% of the battle. It takes a few weeks of self-enforced daily use to get your brain around Emacs, but once you do, you'll find that it is well worth the effort. Then you discover how the other major modes work and there is simply no going back.

I would suggest just getting acclimated to using the basics navigation keys, then when you find yourself using the mouse too often for some certain task, look up the hot key to do that task.

I started up by learning:

C-f, C-b, C-p, C-n, then:

M-f, M-b, then:

C-a, M-a, C-e, M-e, then:

C-[space], C-w, M-w, C-y

It really is a slow process of learning a few keys at a time, but you'll find that once you understand the mnemonics and get your muscle memory in line, you'll find that you can learn several key-bindings quickly. The initial hump is sort of steep, but then it goes really fast.

...and at the risk of turning this into a lengthy "how (I think you should) to learn Emacs" thread, learn the help commands. _How_ to look up the hot key, how to look up the documentation for a key sequence, etc.

Once you have your head around how Emacs works, and that it's self-documenting and you can dig into it, the path gets a lot smoother.

There is also Marco Baringer's screencast on using slime to work with common lisp: http://www.youtube.com/watch?v=_B_4vhsmRRI

Can you recommend any good videos? :)

This project can help with printing statements: https://github.com/danielribeiro/print-foo/tree/prit

Which is helpful for quick inspection.

That is awesome. Thanks. You might want to post this on the SO question I asked.

For those not familiar with Emacs, IntelliJ IDEA with La Clojure is also an okay choice. I use IDEA for Python, Java and Scala; and still switch to Emacs when I code in Clojure. The reason is that Emacs has really strong toolset for LISP, where many of the features are missing from other environments, or implemented partially.

Slime/swank (nrepl replaces it, but I'm just slowly transitioning to it), provides code completion, documentation lookup, REPL, macro expansion and even live code updates on a running application; which can be a bit of a pain to setup on other editors. And the integration in Emacs is really great, as the repl buffer is really just a text buffer, the same as the one you are coding in.

But the biggest reason for me to code LISP in Emacs is paredit. It really makes all the trouble with balancing parenthesis and moving around the sexps really easy. It might seem counter intuitive and a bit troublesome at first, but I really recommend you to try it. For a short and enthusiastic video on paredit, see http://www.youtube.com/watch?v=D6h5dFyyUX0 -- and maybe the other Emacs Rocks! videos to learn more about modern Emacs.

So much slurping and barfing. I hear this guy's voice in my head every time I manipulate sexprs in paredit.

On Emacs, I've been a long time vimer and one day I decided to try Emacs to see the world from a "higher order". First thing that I found superior to vim is that the level of extensions are beyond what vim mods could do. Being benefit from elisp, emacs can do pretty much anything your OS(unix) does, with the emacs interface on top of it. That means, you can use emacs stuff all over your "buffers"(working windows). And if you are a coder, you will be amazed by: 1. being able to code, while talk about your code on irc/freenode seamlessly; 2. being able to code, while open a api website, and move code examples between them. And things do not break easily like vim does, yet everything are an order more finished and intelligent than the vim counter parts.

Saying all these, the reason I am still using vim is that my CTS prevents me from using emacs all the time, and most of the advantage Emacs brings can be achieved by a good tiled windows manager such as xmonad.

One of the big things we'd like to accomplish is building a book out of things the community needs. I've felt this pain myself. I'd strongly suggest you submit "idea" issues for the topics you feel most uneasy about.

https://github.com/clojure-cookbook/clojure-cookbook/blob/ma...

Done, basically just linked back to these comments. Hope that's good enough. I can't write something more thorough than that right now.

Many good responses about using emacs. For those who prefer vim, you can use ScreenSend and paredit to get a similar experience (and there are other options, but that's what I use).

For vim users, tim pope's fireplace plugin provides an integrated "quasi" repl in vim: https://github.com/tpope/vim-fireplace. The only downside is I can't seem to figure out how to use it for clojurescript. Also vim-slime is amazing for general purpose sending to another tmux-pane: https://github.com/jpalardy/vim-slime. I use vim-slime when I'm working with clojurescript.

What percentage of the book revenue do you plan to share with contributors?

O'Reilly is has been flexible enough to let us crowdsource this and release it freely to the community, but as far as the commercial sales of the print version go, we're following a fairly traditional publishing model.

What author royalties there are will go towards getting print versions of the book to our largest contributors, and then to Ryan and I as editors.

I don't think it would be feasible to split the royalties fairly amongst all our contributors; not only would it be a large overhead, but the actual amounts would be pretty tiny unless you've written a pretty large proportion of the book. And if you do that, we'd be happy to talk to you about sharing some of the royalties.

"the actual amounts would be pretty tiny unless you've written a pretty large proportion of the book"

What proportion of the book do you expect the editors to write?

That's a tough question to answer right now since we don't know how much help we're going to get. I'm expecting Luke and I write at least half of the book–I'd be ecstatic if we got that much help.

On the other hand, should contributions be extremely low, we are still on the hook with O'Reilly to deliver all of the book.

Reply on news.ycombinator.com