clj-commons/formatter

Building blocks and discussion for building a common Clojure code formatter

formatter's Issues

Formatting let bindings

Similar to #7 on formatting maps, how should let bindings be formatted? Should all of the init-forms (right hand side) be aligned, or have a ragged alignment?

(let [a nil
      very-long-symbol {}])

;; or

(let [a                nil
      very-long-symbol {}])

Should lines that are destructuring collections be handled differently? They can get very long and would cause large gaps in let bindings if they were included.

Feature prioritization

I see that communication on this project appears to have slowed down, and as an unknown Clojure developer, that saddens me. So, I'd like to try to stoke the fire a little and propose a way to get out of the deadlock that seems to have occurred on a number of issues.

In some cases, two features we would like to have are impossible to meet at the same time. For example, supporting semantic indentation cannot occur without either versioning the tool or supporting configuration.

It's difficult to move forward regarding the miscellaneous trade-offs without establishing which features are most important. For example, I think that looking similar to existing styles is less important than surviving language evolution. Judging by the other issue threads, that is not a universally shared belief.

Here's how I would begin prioritizing... just to kick things off:

1. Standalone specification, independent of its implementation.
2. Specification should be forever version 1.0.
3. Specification must not be configurable.
4. Specification must be able to be implemented efficiently in many environments.
5. Specification should be easy to implement efficiently in many environments.
6. There should be only exactly one acceptable way to format a non-comment.
7. When comparing two style options, select the option that produces smaller diffs.
8. If diffs are equivalent, select the option that produces fewer lines.
9. Comments should not be modified in any way, if possible.
10. A command-line tool should accompany the specification on release as a means of validating ease of implementation and edge-case handling. It can also be used as a bridge to native support in various IDEs.

Notably excluded:

1. Semantic indentation -- Incompatible with 2) and 3) above. If someone wants this, or to extend the specification in a configurable way, that's their prerogative.
2. Ubiquity -- Existing projects probably won't change, and some people will never use something without semantic indentation.
3. Semantic canonicalization (ex. ordering of ns forms). This is at odds with 2) and 5), as it requires special casing forms that are known to have ordered-values-that-are-not-really-ordered.

Some design decisions get made easier by the above. For example, how long should lines be? 7) and 8) take priority, so you could take a bunch of projects in the wild, run a formatter with a variety of line lengths, and choose whatever is working the best.

I appreciate that there are people thinking about this problem, and I'll end up using whatever you all decide on, regardless of if makes the same choices I would make. Thanks for reading, and good luck.

Should there be a space between #_ and the next form?

Should there be a space between #_ and the next form? What should happen with multiple #_s?

I'm often pretty sloppy with #_ when I'm writing them as they are generally a debugging aid or for work in progress. However it would be good to have a standard formatting rule for how to handle them.

Empty lines between forms

How many empty lines should go between forms? A few options here:

• Don't touch this at all, leave any newlines between forms alone
• One line between each form
• Two lines between each form

Originally posted by @PEZ in #2 (comment)

---

Between top level forms
Some people suggest to use two lines. Having tried that, I have kind of started to like it. But I am not using it for all forms.

(def foo :foo)
(def bar :bar)


(defn re-pos-first
  "Find position of first match of `re` in `s`"
  [re s]
  (if-let [m (.match s re)]
    (.-index m)
    -1))


(defn split-into-lines
  [s]
  (clojure.string/split s #"\r?\n" -1))


(defn enclosing? [text]
  (let [ast (cljify (paredit/parse text))
        children (:children ast)]
    (and (= 1 (count children))
         (= "list" (:type (first children))))))

I think the pattern I follow might be that forms that are often one-liners get zero lines between them and otherwise I opt for two. Maybe the formatter could use these rules:

• No empty lines between one-liner forms
• X (whatever we agree on) empty newlines between multi-line forms, as well as between one-liner forms and multi-line forms.

Removing extra whitespace?

There are a few places where Clojure programs can accumulate trailing whitespace. In the listings below | denotes the end of the line.

At the ends of lines after source code

(def v nil)       |

Between lines of source code within a form

(defn best-allowed-language [accepts-header available]
  (let [accepts (->> (string/split accepts-header #"[\s\r\n]*,[\s\r\n]*")
                     (map split-qval)
                     (into {}))
                     |
        score (fn [langtag]
                (or
                 ;; "A language-range matches a language-tag if it exactly equals the tag"
...

At the end of a source code file

(def v nil)

|

Different programmers and editors have different behaviour for how they treat extra whitespace. This can lead to churn in source control diffs when different programmers work on the same file. I think it would be beneficial for this spec to define a policy for handling extra whitespace. I'm personally in favour of removing all three kinds of whitespace, but would like to open this up for discussion.

Formatting map literals

Should map values be aligned, or should they have a single space between keys and values? E.g.:

{:a 1
 :xyz 2}

;; or

{:a   1
 :xyz 2}

Do we want to control formatting of whitespace within a map values at all? (probably)
How do we handle formatting maps when you have several but not all key-value pairs on the same line?
How do we handle formatting maps when the value is put on the line below the key? e.g.

{:a 1
 :b 
    2}

;; or

{:a 1
 :b 
 2}

Aligning map values may lead to more readable code (at least for some people) but can introduce more churn in source control diffs as keys are added and removed over time. There are often ways to remove whitespace from diff views, but this may still be an issue for some people.

Reordering ns forms?

Do we want to reorder ns forms to follow something like Stuart Sierra’s style guide? (I’m really in favour of this personally).

If we do want to reorder ns forms, what should they look like? What are some of the edge cases that we would face here?

I'm not sure whether we'd want to do line breaks in the way Stuart suggested. This tool would be able to sort namespaces programmatically, not manually in an editor.

This recommendation is slightly different from common practice, but it makes it easier to sort names with editor commands (sort-lines in Emacs).

How do we deal with comments?

How should we deal with comments? Is there a difference between ; and ;;?

Reading discussions of other people building source code formatters, comments came up many times as a very tricky thing to deal with properly.

Do we only support UTF-8 files?

UTF-8 is the dominant encoding for source code, though by no means is it the only one. One decision that the tool/spec would need to make is whether to support reading and writing non-UTF-8 encodings. As a New Zealander working in English, I haven't had a lot of exposure to alternative text encodings. I'd especially welcome the perspectives of (probably non-Western) Clojure developers who may use alternative text encodings.

Formatting reader conditionals

How should reader conditionals be formatted? Should the conditional itself be outdented so that the code flows better, or just treat it as a regular form?

Indentation

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.