Clojure Style Guide | Hacker News Reader

Clojure Style Guide

github.com

75 pointsjgrodziski27 comments

    ;; good
    (defn print-seq [s]
      (when (seq s)
        (prn (first s))
        (recur (rest s))))

    ;; bad
    (defn print-seq [s]
      (when-not (empty? s)
        (prn (first s))
        (recur (rest s))))

Why use `seq` instead of `not-empty`?

    (defn print-seq [s]
      (when (not-empty s)
        (prn (first s))
        (recur (rest s))))

(when (seq s) ...) reads to me as "do this as long as I can treat s sequentially". The following operations on s require it to be seqable, so it's like a runtime type check. not-empty is less direct, and feels like it's assuming that s is seqable.

Of course, not-empty is implemented with (when (seq)), so there's no REAL difference. At the end of the day, (when (seq)) is what people use.

This interpretation is error-prone. (seq 1), for instance, throws an IllegalArgumentException at runtime. Meanwhile, (seq nil) returns a falsey value even though in many cases it's possible to transparently pass nil in place of a collection of any kind.

Essentially, seq already assumes that its argument is seqable. Don't use it to test an argument of unknown type for seqability; prefer something like the seqable? function from core.incubator [1], or a different core function like coll? or sequential? where the semantics of one of these will do.

[1] https://github.com/clojure/core.incubator/blob/master/src/ma...

I don't know any Clojure, but I guess it's for the same reason why

  if lst:
    # do something with lst

is preferred to

  if len(lst) > 0:
    # do something with lst

in Python. It becomes more obvious when you use descriptive names:

  if customers:
    # do something with customers

... but involves such an overloading of the nature of truthiness! All to match a really ad hoc syntax sugaring of English?

    if X ==> if there exists some X

In Python, "if there exists some X" would be more like

     if x is not None:

In Python, [] (empty list) and {} (empty dict) are == False but are not None. They exist, and their types are List and Dict rather than NoneType, but they are "falsey" because they are empty.

  (not-empty coll)

is the same as

  (when (seq coll) coll)

Yeah, it's worth noting that not-empty is the flip-side to empty (which returns an empty coll of the same type as its argument), as opposed to empty?.

There's still debate on this (https://github.com/bbatsov/clojure-style-guide/issues/44). It's the suggested style mostly because Rich (Clojure's creator) promotes it.

I agree that this is a pretty good style guide, in the sense that it captures a large portion of what Clojure programmers consider to be good style.

A few words about semicolons for comments. Lots of Clojure code uses ; and ;; and ;;; to indicate levels of comment nesting. I get that multiple semicolons are intended to indicate hierarchy / sections / nesting. Some editors use it for auto-indentation. (However, I don't think editors really need multiple semicolons to do a good job of indentation; mine does fine without.)

Personally, I find one semicolon to be enough to indicate a comment at any level. Context tells the rest. So I am not on-board with multiple semicolons. One, it looks ugly to me. Two, using more than one seems unnecessary -- and unnecessary things are good to avoid unless they add value.

Who else agrees? Is there something I'm missing?

Sometimes I use an editor with a highlight and comment feature, and if I comment out a block of code, some of those intertwined comments will have the double semicolon. Another neurosis I have is using multiple for stuff that I've yet to delete but want to make sure I don't accidentally uncomment but that is dumb and what version control solves. Outside of these unconvincing uses I'm not familiar with this nested comment idea but I couldn't criticize it given the funny things I do.

I believe that this convention is borrowed from Common Lisp. I always thought of it more as a way to highlight importance. Three semicolons for block comments outside of top-level constructs, which usually explain the purpose or usage of the following expression (usually a function definition). Two for comments inline with function body code. And one for trailing comments on a line, where space is limited and the comment is least important to understand code structure.

The conventions are even mentioned in the Common Lisp specifications: http://www.lispworks.com/documentation/HyperSpec/Body/02_ddb...

The use of one or more semicolons is older than Common Lisp. Maclisp had it in the 1970s, but earlier with different semantics - it had semantics for formatting code. Then it was changed a bit with the use of Emacs.

I've used Marginalia[1] in the past, which more or less embeds markdown in clojure comments as a sort of literate programming lite. It has the payoff that it can generate rather nice docs[2] but without something like that, I'm not sure there's much benefit to the hierarchy.

[1] https://github.com/gdeer81/marginalia [2] http://gdeer81.github.io/marginalia/

The thing I most scratch my head about in my Clojure code is when to optimise function arguments for each of thread-first/thread-last/partial etc. Some patterns are fairly established, like predicate first, coll last, but I'd be intrigued to hear some more rules of thumb.

I'm a bit confused about the require refer all vs use. Can someone explain why use is bad in that context (or in general)?

Link: https://github.com/bbatsov/clojure-style-guide#prefer-requir...

UPDATE:

Looks like there's a GH issue thread on the subject: https://github.com/bbatsov/clojure-style-guide/issues/16

Both :use and :require :refer :all slurp symbols into your namespace unqualified. This behavior can cause confusion when someone reading your code tries to figure out which symbols are defined where. Most of the time, more explicit alternatives are preferred:

  (:require [foo :as f])

gives the required namespace a short alias with which symbols defined in that namespace can be qualified, while

  (:require [foo :refer [bar baz quux]])

explicitly provides a set of symbols to import unqualified.

Generally speaking, :require :refer :all is also considered non-idiomatic. In fact, ClojureScript has explicitly avoided supporting both :require :refer :all and naked :use [1]. Backwards compatibility seems to be the only reason either is still supported by Clojure on the JVM.

[1] https://groups.google.com/forum/#!msg/clojurescript/SzYK08Od...

I totally agree about requiring :as or :refer to specific functions, but it still seems like the clojure team prefers naked `use` over `require refer all`, so should the style guide be changed to allow naked `use` in some circumstances?

I guess a popular example is `(:use clojure.test)`

Makes sense to me, although I suppose there's probably an argument to be made in favor of the uniformity that comes with using :require for everything.

(:use clojure.test) is probably a worthy exception – 90% of the time I see :use in the wild, it's in exactly that context :)

Seems to me like Clojure is experience a popularity surge on HN lately. I wonder what's driving this.

Maybe my perception is just biased because I'm currently learning Clojure.

That's strange, because I also noticed that, and I'm also starting to learn Clojure.

Same here

I have also been convinced to start learning clojure. Also on the hn posting thread, a company called fracture had a relatively interesting job application, and if the kind of people who write clojure write tongue in cheek shit like then I want to start learning.

Clojure stories are experiencing a slight surge, but not an unusual one. When I search on Hacker News by date, like https://hn.algolia.com/?q=clojure#!/story/forever/prefix/0/c... (UNIX timestamps format), I can calculate that there are more stories with “Clojure” in the title than last month, but it is within normal fluctuations.

In the last four month-long periods, beginning with April 9 to May 9 and ending with July 9 to August 9, the number of “Clojure” stories were [36, 41, 32, 41]. So the 41 stories of the most recent month is more than the previous month, but the same as the month before that.

My completely unfounded theory: Clojurescript is starting to get a lot of traction because of David Nolen's Om which has caused a surge of interest based on its excellent performance characteristics and clean and easy to reason about code (mainly due to the use of persistent data structures). This naturally leads to people getting interested in Clojure the language as well

`Prefer .. to -> when chaining method calls in Java interop.`

That works if there's only Java calls in your chain. I, for one, prefer to use the more generic threading macros.

Much as I loathe self-proclaimed "best practice", I find this style guide agreeable. I'll quibble with the author's superfluous use of comp/partial as a documentation aid, and the picayune advice to use single-sentence-spacing in comments deserves an eyeroll. But for the most part this is all good stuff, and is worthy of consideration. Pay attention, n00bs.

Reply on news.ycombinator.com