Indentation

[PEZ]

I, for one, start to think about indentation first thing when formatting is mentioned. So therefore this thread on that issue. As the plethora of zprint indentation options show us there are a plethora of ways people indent Clojure code.

[PEZ]

My vote is on the indentation suggestions of @tonsky's Better Clojure Formatting. They are truly simple and can survive just about any development of the Clojure language:

• Multi-line lists that start with a symbol are always indented with two spaces,
• Other multi-line lists, vectors, maps and sets are aligned one space after the open delimiter.

Note: I updated the second rule to disambiguate it, as per @shaunlebron's comment below.

Pasting the examples from the article here.

(when something
  body)

(defn f [x]
  body)
  
(defn f
  [x]
  body)
  
(defn many-args [a b c
                 d e f]
   body)
  
(defn multi-arity
  ([x]
   body)
  ([x y]
   body))

(let [x 1
      y 2]
  body)
  
[1 2 3
 4 5 6]

{:key-1 v1
 :key-2 v2}
 
#{a b c
  d e f}

(or (condition-a)
  (condition-b))
  
(filter even?
  (range 1 10))
  
(clojure.core/filter even?
  (range 1 10))

(filter
  even?
  (range 1 10))

Another good reason to keep the rules as simple as this is that it will be a lot less to learn for newcomers. They can concentrate on learning the idioms of the language instead of idioms of indentation style. In fact I think most of us will benefit from the easier parsing of the code when we always know what indentation to expect.

A thumbs up on this comment means you vote for these suggestions. (I recommend reading the article before weighting in.)

[zane]

While I admire the spirit behind this effort I am against this particular proposal for the simple reason that code indented based on these rules conveys less information than code indented based on the rules in the Clojure Style Guide.

Let me explain.

Lisp language communities have traditionally embraced semantic indentation (indenting subforms differently depending on the symbol in the operator position) because it allows the reader to derive information about a form even if they don't recognize the symbol in the operator position.

For example, if the reader instead encounters a form where the operands after the first have been given visual prominence by being dedented, like so

(foo bar
  baz ; no longer vertically aligned with bar
  qux)

then the reader can assume that foo is a macro with body parameters like when, with-out-str, etc.

If the reader encounters a form where all the operands are aligned

(foo bar
     baz
     qux)

then the reader can assume that the form is not a macro with body parameters.

Without this visual cue the burden of differentiating between these two cases falls on the reader.

Admittedly implementing semantic indentation is harder than implementing the proposal outlined above, but it is effort well spent. It is an investment that will pay dividends every time code indented by that formatter is read.

[zane]

Additionally, vertically aligning function arguments spanning multiple lines has the added benefit of being easy to scan. A reader looking at one argument to a function need only move their eyes up or down within the same column to find the other arguments to that function.

Similarly a programmer with their cursor at the start of the first argument to a function need only move their cursor down to find the rest of the arguments to that function. This is important if one wants to use keyboard macros to record and replay a sequence of actions on each of the arguments.

[claudiu-apetrei]

Seems like it's already supported by editors https://twitter.com/CursiveIDE/status/1070984513163997189

Configured cursive that way and have been trying it out on my code.
So far so good, actually wish I knew about this option sooner... been fighting with Cursive's macros indentation (resolve-as) every time I start a project, now it's just indented the way I want it to without any config.

Personally really like having fewer & simpler formatting rules than the current clojure-style-guide even if it means sacrificing semantic indentation hints and preferences (my eyes are still adjusting to the new way threading macros are indented).

Edit
https://www.braveclojure.com/do-things/

Syntax
Clojure’s syntax is simple. Like all Lisps, it employs a uniform structure, a handful of special operators, and a constant supply of parentheses delivered from the parenthesis mines hidden beneath the Massachusetts Institute of Technology, where Lisp was born.

For such a simple language feels a bit strange to have so many indentation rules to remember.
The new proposal seems like it's a bit more in tune with how clojure syntax is presented.

[shaunlebron]

@zane wow, I didn't know indentation was a shortcut for differentiating functions and macros. Would the following be a decent compromise?

;; ✅two-space indentation
;; ✅child arguments are aligned => foo is function
(foo
  bar
  baz
  qux)

;; ✅two-space indentation
;; ✅first child separated => foo is macro
(foo bar
  baz
  qux)

This indentation system is still flexible in that it gives you full control of newline characters. I think that's probably the sanest way to create an indentation formatter without incurring the cost of including a semantic analyzer.

[shaunlebron]

Other multi-line lists, vectors, maps and sets are aligned with the first element (1 or 2 spaces).

Possibly ambiguous, since this would pass the check (not intended right?):

[ 1 2 3
  4 5 6] ;; <-- two space indentation to align with first element

I think the rule can be rephrased as "one space after the open delimiter", so it includes:

[1 2 3
 4 5 6]  ;; <-- one space indentation after the open delim "["

#{1 2 3
  4 5 6} ;; <-- one space indentation after the open delim "{"

Also works for delims with longer prefixes:

#?@(:clj [...]
    :cljs [...])

#queue[foo
       bar]

[zane]

@shaunlebron It's a little more subtle than differentiating between macros and functions. The rules in the Clojure Style Guide help readers determine whether or not the symbol in the operator position is a macro that has body parameters. I've updated my comment above to try to make that more clear.

For example, when has its body dedented:

(when (even? n)
  (println n)
  (inc n))

Similarly with-out-str also has its body dedented:

(with-out-str
  (println "foo")
  (println "bar"))

However, or does not even though it is a macro:

(or (foo? n)
    (bar? n)
    (= n 7))

[zane]

To take a step back, there's a reason why auto-formatters like gofmt are less popular in Lisp-like languages: In a constrained language like golang it's easy to enumerate all the "special forms" upfront and choose the best indentation rule for each. In Clojure however users can extend the language via macros, making the total set of "special forms" (and the number of different kinds of special forms) unbounded.

To me this raises the question of whether a one-size-fits-all indentation rule is even desirable. I certainly can't imagine all the different kinds of macros people might write, nor can I imagine all the kinds of information a macro writer might want to convey to people reading code that uses their macro. This is why (I presume) Cider cedes authority on the matter of indentation to the macro writer via indent specs.

[arichiardi]

Agree to the point that the rules above are simple therefore good. I also agree to the points @zane is making.

I guess if the goal of this issue is to establish "sensible defaultz" then probably something along the lines of the two rules might be good.

However I do not see myself using only those, realistically - that is why I really liked the approach that zprint has in defining "format like this" config options + the tons of options. For reference the tslint tool has way way too many options in comparison and folks have developed presets. I do not see it as a problem personally.

So maybe my question here would be, what would be the outcome of this vote?

[shaunlebron]

@zane great description of the problem, thanks for clarifying.

Interesting precedent: This made me write about how elm-format inspired prettier to let the user nudge the formatter for cases too ambiguous to automate. Thus, proposing:

Rule 3 Proposal

3. multi-line lists are indented to "first-arg alignment" if and only if the 2nd line is indented as such

✅ Triggered:

;; before
(foo bar
     baz             ;; <-- 2nd line is "first-arg aligned"
  qux)

;; after (rule 3 triggered)
(foo bar
     baz
     qux)

❌ Not triggered (falling back to two-space indentation from Rule 1)

;; before
(foo bar
 baz                ;; <-- 2nd line is NOT "first-arg aligned"
  qux)

;; after (rule 3 NOT triggered)
(foo bar
  baz
  qux)

Takeaways:

• provides strict formatting for both legitimate indentation choices
• specifies a well-defined nudge to let user pick (without explicit indent spec or analysis)

Since there's precedent for doing something like this in popular formatters, this might help break Lisp out of its unique indentation paralysis.

[tonsky]

Semantic indentation is actually quite dangerous. Because it will make mistakes (yet unknown forms, lib author hasn’t provided indentation rules etc) and it will convey incorrect meaning. To me this is no-go. I prefer something with less info but reliable 100% time rather than something with more info but 10% chance it might be incorrect.

The only solution I see here is to let code author decide indentation as she writes code (~Rule 3 proposed by @shaunlebron). But do you really need that info? If you see when or or form do you really need indentation to help you figure out what they are?

I also have an argument against aligning arguments to the first one. Everything becomes too indented too quickly. Function names are usually not as short as foo/or/and. And they often include namespaces. If I have something like

(utils/format-paragraph p
                        out
                        opts)

everything is suddenly indented 24 spaces in, even though nesting level has just increased by 1.

Indentation ~ nesting level is another benefit coming from my proposal. I believe it makes code easier to read (you can approximate nesting just from a quick glance over indentation). It also makes code easier to format, as everything becomes much less spread horizontally.

[tonsky]

Just a reminder: we are not inventing just another formatter here. We are trying to find a solution that would work everywhere for everyone. I believe it makes relying on runtime information (like indentation rules specified on forms) a no-go

[shaunlebron]

worth making this clear:

Rule 3's relation to clojure-mode:

@bbatsov's clojure-indent-style specifies three different styles, and branches further based on the placement of bar in examples below:

1. :always-align

   (foo bar              ;; <-- formatted based on `bar` on 1st line
        baz)             ;;     (outcome A)
   
   (foo
    bar                  ;; <-- formatted based on `bar` on 2nd line
    baz)                 ;;     (outcome B)

2. :always-indent

   (foo bar              ;; <-- formatted based on `bar` on 1st line
     baz)                ;;     (outcome C)
   
   (foo
     bar                 ;; <-- formatted based on `bar` on 2nd line
     baz)                ;;     (outcome D)

3. :align-arguments

   (foo bar              ;; <-- formatted based on `bar` on 1st line
        baz)             ;;     (outcome A)
   
   (foo
     bar                 ;; <-- formatted based on `bar` on 2nd line
     baz)                ;;     (outcome D)

Rule 3 allows outcomes A,C,D but not B.

[kkinnear]

In order to explore the ideas expressed by @tonsky, I hacked up zprint to do what I think he proposed in his blog post. I may, of course, have misinterpreted what he had in mind. I have put the resulting build artifacts in a release zprint-std-0.1.1

There are two graalvm (i.e. fast) binaries there, one for macOS and one for Linux, and an uberjar for everyone else. These things read from stdin and write to stdout.

Note that these are experimental, with almost zero testing. These are not production releases, these are prototypes to play with.

I did this for several reasons. In part to see how hard it would be (not very, since these are simple rules), and in part so that I could see what the results looked like beyond the trivial examples we all tend to use.

Do I think that this is the formatting approach that should be chosen? I'm mixed. It is future proof. I don't expect I'd be formatting my code this way anytime soon, as (unsurprisingly) I like what zprint does by default. That said, I ran this over all of clojure.core looking for some functions that would really look bad. I expected to find plenty, and I found only three or four that looked a bit bad. The only things that I think it seriously fails on are specs. But then pretty much anything without the zprint-style constant pairing is going to fail for specs.

If the code started out looking good, this approach mostly doesn't make it look terrible. If it started out looking terrible, this formatting approach will make it some better, perhaps enough better?

Try it on your code. See what you think.

Edit:

I managed to forget to work through how zprint's current comment handling interacts with the code I added for trying out @tonsky's formatting approach. If you have problems with comments messing up the output, try this, it should help:

./zprintm-std-0.1.1 '{:comment {:inline? false :wrap? false}}' <infile.clj >outfile.clj

If that doesn't fix things, please add to the issues in the zprint-std repo.

[shaunlebron]

@kkinnear is there code available for that?

i had a thought to fork parinfer's code to do this, but only if the rules stay simple (it can only handle indentation correction). small code size and annotated markdown test cases would probably help prototyping