Clojure Style Guide

[Colin Fleming]

Hi everyone,

There's been a bit of discussion recently on a couple of clojure-mode tickets that I thought were worth discussing here. The tickets are #265 and #266, and they later led to PR #96 on Bozhidar Batsov's Clojure Style Guide. The part of the discussion I wanted to raise starts here, where there's some discussion around the nature of the style guide itself.

Bozhidar clearly sees himself as the steward of a community style guide, something he's done to great success with the Ruby style guide. However it seems that there is a significant part of the community that didn't see it that way, and had seen it more as his personal style guide that he happened to put out there. I'm interested in starting a discussion around this because I do think it's valuable to have some degree of community consensus around these issues, specifically so that tools can have consistent defaults.

That said, one of the defining features of lisps in general is that they permit essentially unlimited flexibility, and in my experience programmers in general really don't like being told what to do, especially around indentation. So, I'd like to ask the obvious initial question - do we as a community think that there is value in having a style guide like this? If so, to Marshall's point on the list, do we think it should try to mandate what people should be doing, or should it describe what they actually currently do in real code, even if that's the result of historical accidents?

For what it's worth, from my point of view I definitely think that a guide like this is useful, and I've referred to Bozhidar's guide myself from time to time when trying to decide what to do for a particular feature in Cursive. However I do think that it needs more flexibility than it currently has - there are some things marked in there as "bad" that I'd like to see downgraded to "prefer the other way unless you have a good reason", which of course I always feel like I have. In particular, some of the reasoning behind the linked changes above I think needs to be more flexible - there are good use cases for customising indentation for some functions, for example.

Of course, if we decide that we do want a guide like this then we can spend many happy years arguing about what should go in it, but first things first :-)

Cheers,
Colin

[Lars Andersen]

My view on this is very much along the line of discussions about whitespace.  While I have opinions about these matters, for the most part I don't want to think about it--I have more pressing concerns.  What's important to me is consistency within a code base.  Just like with whitespace, I don't want to introduce spurious changes into all my diffs when working with other people.  I also don't want to customize 50 editor variables to get sane defaults which I have to tweak for various environments (work, home, contributing to open source projects).

Supporting different styles is a laudable goal, but I hope we can agree that the defaults should be similar in all editors to reduce friction when working with others.  Using a style guide maintained by the community for those defaults make a lot of sense to me.

[Laurent PETIT]

I agree that if all tools could agree on sale out of the box defaults, this would be very valuable to users and clojure in general. 

Maybe a less ambitious goal than getting the whole community agree on standards could be tool authors to agree on shared defaults. Which of course doesn't prevent the tools to offer additional options, but activating those would require users to explicitly customize the tools settings. 

Le samedi 20 décembre 2014, Lars Andersen <ex...@expez.com> a écrit :

My view on this is very much along the line of discussions about whitespace.  While I have opinions about these matters, for the most part I don't want to think about it--I have more pressing concerns.  What's important to me is consistency within a code base.  Just like with whitespace, I don't want to introduce spurious changes into all my diffs when working with other people.  I also don't want to customize 50 editor variables to get sane defaults which I have to tweak for various environments (work, home, contributing to open source projects).

Supporting different styles is a laudable goal, but I hope we can agree that the defaults should be similar in all editors to reduce friction when working with others.  Using a style guide maintained by the community for those defaults make a lot of sense to me.

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Laurent Petit

[Laurent PETIT]

s/sale/same

--

Laurent Petit

[Colin Fleming]

Yes, perhaps just agreeing on sane defaults is a more achievable goal. Cursive currently does not indent everything exactly according to the guide by default. I would also not like to see tools' ability to implement more sophisticated formatting hampered by an overly restrictive guide either, since a lot of users have requested that Cursive do different things with particular forms, but having agreed defaults doesn't conflict with this.

[Laurent PETIT]

Let's start the list ! :-)

[Fluid Dynamics]

A way to hint indentation to the tooling would be nice.

Perhaps a metadata on vars such as {:body-indent #{then-clause else-clause}} that could tell tools to indent an "if" this way:

(if condition
  then-clause
  else-clause)

instead of this way:

(if condition
    then-clause
    else-clause)

rather than the current ad-hoc special-casing that seems to be used at present. (Ad hoc special-casing would still be needed for special forms, including "if", but this could be used with macros and perhaps with functions if someone wanted that.)

(Formal specification for that suggestion: the metadata key :body-indent should have a value that is a set of symbols, which are some subset of the symbols appearing in arglists of the bound macro/function. Editors and pretty-printers and other tools would take this as a hint to indent the corresponding parameters only two spaces, if on lines of their own, rather than to align with parameters inline with the operator on the form's first line.)

[Timothy Baldridge]

I recently browsed parts of that guide and was surprised how many bits I disagreed with. Especially around the "one space in these rare cases" bits. Not that that is a bad thing it's just my personal opinion that everything should always use two space indentation.

And on a client project recently, it was decided (when I wasn't around) that the arguments to a function should always be on a newline:

(defn foo
  [x]
  (+ x x))

Instead of:

(defn foo [x]
  (+ x x))

I disagree with this idea also, but whatever, it's just style. It's not like I suddenly can't read Clojure code since it's in the wrong style. 

With so many different views, I think it's unwise to lock any editor into any style. Instead give users options, and update the Clojure Style Guide with the following (paraphrased) quote from Pirates of the Caribbean: "this Code of Styling is more what you'd call "guidelines" than actual rules."

Timothy

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

“One of the main causes of the fall of the Roman Empire was that–lacking zero–they had no way to indicate successful termination of their C programs.”
(Robert Firth)

[Laurent PETIT]

Sure, Tim,

I also remember having disagreed with a fair amount of rules, and the very prescriptive style. 

The idea of just agreeing on same defaults for editors seems sufficient. Given sufficient lazy users like me, this one single rule of default values should be sufficient to help spread a common convention ;-)

--

Laurent Petit

[Fluid Dynamics]

On Saturday, December 20, 2014 9:30:47 AM UTC-5, tbc++ wrote:

I recently browsed parts of that guide and was surprised how many bits I disagreed with. Especially around the "one space in these rare cases" bits. Not that that is a bad thing it's just my personal opinion that everything should always use two space indentation.

And on a client project recently, it was decided (when I wasn't around) that the arguments to a function should always be on a newline:

(defn foo
  [x]
  (+ x x))

Instead of:

(defn foo [x]
  (+ x x))

I disagree with this idea also, but whatever, it's just style. It's not like I suddenly can't read Clojure code since it's in the wrong style. 

My own tendency is to put the arglist inline with the defn foo iff it's the only arity and there's no docstring. If there are several arities each starts on a line by itself. And if there's a docstring, it's defn foo <newline> docstring <newline> arglist...

Of course, since I aggressively document most functions (even non-publics) I don't tend to use the inline arrangement very often, except on local functions: (fn [x y] (map do-something x (map inc y)))...

[Luc Préfontaine]

Defaults only please. 

There are more pressing needs from dev tools than this sort of thing.

Diversity is what makes us well... different. Our minds are not formatted the same

either. What may look readable to someone may look like garbage to someone else,

the context may also influence comprehension.

If a business wants a more or less strict code style fine. It may well be a decent

requirement given their domain. If they need to tweak 50 variables it's also fine, 

it's an investment they are willing to make.

At various times in the past, focus has been on 'standardizing' how code is written,

up to choosing variable names, presentation, ...

While this may have been valuable in some contexts, no unique agreement has been 

ever adopted and the impact on software quality is nil. It may help a given team

to agree on some conventions but in the large it's not worth the energy it sucks.

I suggest reading a 'Brave New World' for those who think that a stronger initiative 

than defaults is required :)

Or punch out a few thousand cards of Cobol code lines to get the feeling...

Luc P.

Sent from my iPad

[Eli Naeher]

On Sat, Dec 20, 2014 at 8:30 AM, Timothy Baldridge <tbald...@gmail.com> wrote:

 

And on a client project recently, it was decided (when I wasn't around) that the arguments to a function should always be on a newline:

(defn foo
  [x]
  (+ x x))

Instead of:

(defn foo [x]
  (+ x x))

Like you I prefer the arguments on the same line as the defn.

Of course, when a docstring is present (and IMO there should nearly always be a docstring), this is not possible. Does anyone here know why in Clojure it was decided to move the docstring from its traditional-in-Lisp location after the argument list? Perhaps it's just a question of what I'm used to, but it feels very awkward to me. I like to be able to see the arglist while I'm reading the docstring so that I can understand to which arguments it's referring, but in Clojure with a long docstring often times the arglist is not even visible on the screen.

 

-Eli

[Ashton Kemerling]

You can put the docstring after the args, but the tooling won't pick it up. 

--Ashton

Sent from my iPhone

--

[Fluid Dynamics]

On Saturday, December 20, 2014 12:01:31 PM UTC-5, Eli Naeher wrote:

Does anyone here know why in Clojure it was decided to move the docstring from its traditional-in-Lisp location after the argument list?

In a nutshell, arity-overloading.

[J Irving]

It's not a docstring then, just the first expression in the body.

[Ashton Kemerling]

That's true. I'm just saying I've accidentally done that before in single arity functions with no penalty. But if you count on cider or similar picking up docstrings from your own functions you'll want to do it the official way. 

--Ashton

Sent from my iPhone

[Andy L]

Hi,

I realized recently that cohesive pretty formatting LISP programs is a very difficult problem to solve in the first place due to its homoiconicity. There could be some nice approximations but the devil is in the details. That all made me so grateful for what we have and I stopped complaining :-) ... 

Ideally, I wish that `clojure-mode` adapts to the style of given project and helps to format my changes accordingly. Again, probably not so easy to do either.

Best regards,
Andy

[Fluid Dynamics]

On Saturday, December 20, 2014 12:53:41 PM UTC-5, Jonathan Irving wrote:

It's not a docstring then, just the first expression in the body.

Leading to the interesting question: is the compiler smart enough to optimize it away? A string literal has no side effects so if its return value is unused the compiler *can* do so, but *does* it?

Obviously, though, if you're going to put a comment where tooling won't pick it up as a docstring you should just use ; and thereby *ensure* it will compile away to nothing.

[John Jacobsen]

Great to see this discussion on the mailing list, rather than just comments to PRs on GitHub.  And a big thanks to Bozhidar for shepherding the current style guide.

I came to Clojure from Python which has a strict standard (PEP-8) and a linting tool which enforces a standard -- it's been my experience that this provides a net benefit to code quality (and not just in terms of aesthetics).  While I also don't agree with everything currently in the style guide, it does some good in our shop by providing a default to refer to which eliminates some wasted discussion time.

So far the PR process on the style guide repo seems to have worked, more or less -- those in the community who care about these things can weigh in, and there at least can be a discussion before the PR is merged.  Perhaps more process or formality will become appropriate later as the community grows.

Regarding indentation metadata or editor customizations: I've seen Cursive/IntelliJ accept directives for indenting specific forms (usually, macros) and I'd like to be able to do that with clojure-mode in Emacs.

John

[Leon Grapenthin]

Thanks for bringing this up here and linking to the issue I raised on GH. I wanted to start a discussion here as well but have not yet found time. 

My concerns and worries are less about the style-guide in general and more about the indentation change regarding assoc introduced as default in clojure-mode 4.0.0. 

At this point in the discussion (bbatsovs reply here) I don't think there is another way to change his mind than more people in the community trying to convince him otherwise.

TLDR is that bbatsov has decided with release 4.0.0 that indenting assoc in the way introduced more than 6 years ago is not so much of a good idea anymore because it "defies an extremely strong Lisp tradition ". 

I find it personally preferable for the three reasons listed here.

Since bbatsov was so kind to fix threading macros yesterday, I guess he can be convinced about assoc, too.

Regarding the discussion in general: How about agreeing to an EDN structure with indentation hints which can be loaded into any Clojure IDE? This would offer library authors to provide indentation hints for their macros themselves. They could also be added as meta-data to the vars so that during an active nrepl connection the correct indentation for e. g. om/dom forms would be pulled automatically...

Best regards, 

Leon.

[Reid McKenzie]

Protip: you already can. From my .emacs:

(define-clojure-indent
(defroutes 'defun)
(GET 2)
(POST 2)
(PUT 2)
(DELETE 2)
(HEAD 2)
(ANY 2)
(context 2)
(for-all 1)
(such-that 1)
(let-routes 1)
(run-db 2)
(defspec 'defun))

Reid

> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clo...@googlegroups.com
> Note that posts from new members are moderated - please be patient with
> your first post.
> To unsubscribe from this group, send email to
> clojure+u...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
> ---
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to clojure+u...@googlegroups.com

> <mailto:clojure+u...@googlegroups.com>.

[Bozhidar Batsov]

The only catch is that you should do this only for “relatively unique” names, as clojure-mode is not namespace aware. Otherwise you might get

funky indentation in odd places.

—

Cheers, 
Bozhidar

To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.

[Bozhidar Batsov]

On December 20, 2014 at 11:14:14 AM, Colin Fleming (colin.ma...@gmail.com) wrote:

Hi everyone,

There's been a bit of discussion recently on a couple of clojure-mode tickets that I thought were worth discussing here. The tickets are #265 and #266, and they later led to PR #96 on Bozhidar Batsov's Clojure Style Guide. The part of the discussion I wanted to raise starts here, where there's some discussion around the nature of the style guide itself.

Bozhidar clearly sees himself as the steward of a community style guide, something he's done to great success with the Ruby style guide. However it seems that there is a significant part of the community that didn't see it that way, and had seen it more as his personal style guide that he happened to put out there. I'm interested in starting a discussion around this because I do think it's valuable to have some degree of community consensus around these issues, specifically so that tools can have consistent defaults.

I do not agree with everything on the guide on a personal level, which is a clear indication this is not a reflection of my personal preferences. On the other hand every such document needs an editor (or a few editors), otherwise chaos is bound the ensue. When I work on open-source projects I follow the style guide pretty closely, but on personal projects I do whatever pleases me. Even if people/teams/etc don’t agree with everything in a style guide, there’s lots of value in maintaining a consistent code base (which is the same as having a style guide). Forking the existing community guide is one of the easiest ways to quickly set up an internal project/company style guide. 

I believe that having at least some level of community-wide adopted standards simplifies the lives of everyone involved, because we spent less time dwelling on details (e.g. code layout) and more time thinking about solving the problems at hand. I actually want to talk about the value of style of at either Clojure/West or EuroClojure. We’ll see if this will actually happen.

That said, one of the defining features of lisps in general is that they permit essentially unlimited flexibility, and in my experience programmers in general really don't like being told what to do, especially around indentation. So, I'd like to ask the obvious initial question - do we as a community think that there is value in having a style guide like this? If so, to Marshall's point on the list, do we think it should try to mandate what people should be doing, or should it describe what they actually currently do in real code, even if that's the result of historical accidents?

I feel that we should promote the “best” (meaning most robust/sensible practices over those that are historical accidents). What qualifies as a historical accident, however, is rarely clear-cut. I’d argue that the `cond` 1-space indentation was one such case, but few other examples come to mind.

While I realise that people always have personal preferences regarding code style, we should keep in mind that we rarely work by ourselves on a particular project and someone will always have to put their personal preferences aside. When we started the Ruby style guide there was little consensus regarding anything in the Ruby world. Pretty much every project I encountered had a style of its own, which introduced a certain cognitive burden on the readers of its source code. 4 years later there’s widespread consensus on a lot of basic stuff and that’s clearly visible. Sure, there are many aspects on which there will never be a consensus (often for a good reason), but having some baseline definitely beats having none at all. After all - making choices is pretty hard, so the less we have to make the better. 

For what it's worth, from my point of view I definitely think that a guide like this is useful, and I've referred to Bozhidar's guide myself from time to time when trying to decide what to do for a particular feature in Cursive. However I do think that it needs more flexibility than it currently has - there are some things marked in there as "bad" that I'd like to see downgraded to "prefer the other way unless you have a good reason", which of course I always feel like I have. In particular, some of the reasoning behind the linked changes above I think needs to be more flexible - there are good use cases for customising indentation for some functions, for example.

The use of the words “good” and “bad” is somewhat unfortunate I guess; lately we’ve also been using “acceptable” and “preferable” as well. The guide ends with something like “use common sense”. The rules are mostly prescriptive - if you know Clojure well enough and you feel you have to violate some of them you should probably do so.

Of course, if we decide that we do want a guide like this then we can spend many happy years arguing about what should go in it, but first things first :-)

Cheers,
Colin

[Bozhidar Batsov]

Yeah, shared (or at least as shared as possible) defaults would be awesome. I feel that the style guide might provide us with

some insight about what those shared defaults should be.

—

Cheers, 
Bozhidar

[Bozhidar Batsov]

On December 20, 2014 at 4:30:41 PM, Timothy Baldridge (tbald...@gmail.com) wrote:

I recently browsed parts of that guide and was surprised how many bits I disagreed with. Especially around the "one space in these rare cases" bits. Not that that is a bad thing it's just my personal opinion that everything should always use two space indentation.

Can you elaborate on “one space in these rare cases”. I can think of just one case (arguments following function/macro name on the next line) of such indentation and this is something rooted in Lisp’s DNA. :-)

And on a client project recently, it was decided (when I wasn't around) that the arguments to a function should always be on a newline:

(defn foo
  [x]
  (+ x x))

Instead of:

(defn foo [x]
  (+ x x))

I disagree with this idea also, but whatever, it's just style. It's not like I suddenly can't read Clojure code since it's in the wrong style. 

With so many different views, I think it's unwise to lock any editor into any style. Instead give users options, and update the Clojure Style Guide with the following (paraphrased) quote from Pirates of the Caribbean: "this Code of Styling is more what you'd call "guidelines" than actual rules."

This is the final rule https://github.com/bbatsov/clojure-style-guide#common-sense :-)

That said, we should probably mention something similar in the overture. PEP-8 has something similar https://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds

[Bozhidar Batsov]

You can use `.dir-locals.el` to alter the clojure-mode indentation settings on a per-project basis.

—

Cheers, 
Bozhidar

[Bozhidar Batsov]

On December 21, 2014 at 1:12:10 AM, Leon Grapenthin (grapent...@gmail.com) wrote:

Thanks for bringing this up here and linking to the issue I raised on GH. I wanted to start a discussion here as well but have not yet found time. 

My concerns and worries are less about the style-guide in general and more about the indentation change regarding assoc introduced as default in clojure-mode 4.0.0. 

At this point in the discussion (bbatsovs reply here) I don't think there is another way to change his mind than more people in the community trying to convince him otherwise.

TLDR is that bbatsov has decided with release 4.0.0 that indenting assoc in the way introduced more than 6 years ago is not so much of a good idea anymore because it "defies an extremely strong Lisp tradition ". 

I believe I presented a bit more arguments than that. :-)

I find it personally preferable for the three reasons listed here.

Since bbatsov was so kind to fix threading macros yesterday, I guess he can be convinced about assoc, too.

This is unlikely to happen. Few people were upset about the assoc indentation and more greeted it. Not to mention most tools don’t use special indentation for assoc by default. I’ll extend the clojure-mode docs with more info about indentation customizations, which sounds like a reasonable compromise to me for people who disagree with the defaults. People should certainly be able to indent their code however they see fit.

Regarding the discussion in general: How about agreeing to an EDN structure with indentation hints which can be loaded into any Clojure IDE? This would offer library authors to provide indentation hints for their macros themselves. They could also be added as meta-data to the vars so that during an active nrepl connection the correct indentation for e. g. om/dom forms would be pulled automatically...

Best regards, 

Leon.

On Saturday, December 20, 2014 10:14:18 AM UTC+1, Colin Fleming wrote:

Hi everyone,

There's been a bit of discussion recently on a couple of clojure-mode tickets that I thought were worth discussing here. The tickets are #265 and #266, and they later led to PR #96 on Bozhidar Batsov's Clojure Style Guide. The part of the discussion I wanted to raise starts here, where there's some discussion around the nature of the style guide itself.

Bozhidar clearly sees himself as the steward of a community style guide, something he's done to great success with the Ruby style guide. However it seems that there is a significant part of the community that didn't see it that way, and had seen it more as his personal style guide that he happened to put out there. I'm interested in starting a discussion around this because I do think it's valuable to have some degree of community consensus around these issues, specifically so that tools can have consistent defaults.

That said, one of the defining features of lisps in general is that they permit essentially unlimited flexibility, and in my experience programmers in general really don't like being told what to do, especially around indentation. So, I'd like to ask the obvious initial question - do we as a community think that there is value in having a style guide like this? If so, to Marshall's point on the list, do we think it should try to mandate what people should be doing, or should it describe what they actually currently do in real code, even if that's the result of historical accidents?

For what it's worth, from my point of view I definitely think that a guide like this is useful, and I've referred to Bozhidar's guide myself from time to time when trying to decide what to do for a particular feature in Cursive. However I do think that it needs more flexibility than it currently has - there are some things marked in there as "bad" that I'd like to see downgraded to "prefer the other way unless you have a good reason", which of course I always feel like I have. In particular, some of the reasoning behind the linked changes above I think needs to be more flexible - there are good use cases for customising indentation for some functions, for example.

Of course, if we decide that we do want a guide like this then we can spend many happy years arguing about what should go in it, but first things first :-)

Cheers,
Colin

--

[Timothy Baldridge]

I get concerned whenever I see things like "rooted in lisp's DNA". Lisp is data, there is no formatting. If we want to argue tradition, we should stop ourselves and instead argue the points behind the tradition. It's not good enough to say "It's always been done this way..." We instead should say "It's always been done this way because of X". Now we can argue about X, which may or may not be applicable to a language designed decades after these older lisps. Implementing something for tradition's sake is the very definition of cargo culting. 

Timothy