Discussion: formatting options

[gilramir]

Question 1 - Number of spaces per indentation

4?

By the way, you will see in some examples that even if we pick a specific
indentation, we might also have a smaller indentation, or so it seems (nested brackets,
Question 4)

Question 2 - Page Width

I currently have a 100-column page width. Do we want this? 100? 90? 80?

The reason I'm using PrettyExpressive is that other formatters also use similar
pretty-printing algorithms, notably the Wadler-Leijen Algorithm and its
functional variant, Strictly Pretty. In this family of pretty-printing
algorithms, there is a page width, and the algorithm can make the code look
pretty within the page width, but if needed, let it go beyond the page
width and care less about the prettiness.

Some tools, like Golang's "go fmt" don't do this. They honor the line breaks
of the author. If the author wants very long lines, so be it.
"go fmt" isn't producing canonical output, it's just adjusting
the author's formatting to make it nicer.

Since we do want canonical output, we have to enforce a canonical way of
where to break lines. And thus, we need a page width.

The simplest example of this is is Gren's "module" line. If the "exposing" list is short
and can fit in the page width, we can render it on one line.

module Geometry exposing ( Point, area, perimeter )

But if it's long, we can render it in the multi-line format.

module Geometry exposing                                                         
    ( Point                          
    , Shape
    , Circle
    , Rectangle
    , computeArea
    , computePerimeter
    , scaleShape
    , translateShape
    , rotateShape
    )

But also, as an example, a function call that is short stays on one line:

result = renderWidget header content footer

while one that is long enough to reach the page boundary wraps, and its
overflow arguments indent one tab stop:

result =
    renderWidget mainContainerElement headerSectionElement navigationBarElement contentAreaElement
        footerSectionElement

Question 3 - Multi-line "if" predicates

If we are going to have a page width boundary, and thus long expressions
do wrap, how shall we render if/then expression with long "if" predicates?

Example of a short predicate:

    if callSomeFunction then
        runTrue
    else
        runFalse

Example of a long predicate, indented to the same level as the body:

    if (callSomeFunction with lots of arguments that need to
        wrap the line) then
        runTrue
    else
        runFalse

Example of a long predicate, indented to an extra tab-stop, to be visually
different from the body:

    if (callSomeFunction with lots of arguments that need to
            wrap the line) then
        runTrue
    else
        runFalse

This last example is what the formatter is currently doing.

It turns out the wrapping can happen such that the "then" is by itself on a
line. The then is pushed to a line of its own, indented one
extra step (+8) past the branch body (+4):

ifLong x =
    if conditionOne x && conditionTwo x && conditionThree x && conditionFour x && conditionFive x
            then
        trueBranchResult
    else
        falseBranchResult

Is a dangling then the layout we want, or should the then kept attached to the last predicate line?

Question 4 - Indentation of nested brackets

It can appear that nested brackets have 2-space tab stops instead of 4. The
outer [ and its item separators , sit at one tab stop (column 5 here), but
because each item begins with [ / , (two characters), an item that is
itself a bracketed block lines its {, , and } up two columns further in
(column 7) — so the inner brackets read as a 2-space indent rather than 4.

shapes =
    [ { name = "circle"
      , numberOfSides = 0
      , isFilled = True
      , colorValue = "crimson"
      , strokeWidth = 2
      }
    , { name = "triangle"
      , numberOfSides = 3
      , isFilled = False
      , colorValue = "cornflowerblue"
      , strokeWidth = 1
      }
    ]

Is this okay? Or is another rendering better?

By the way, each item also decides independently whether it fits, so a short item can stay
inline while a longer sibling breaks

shapes =
    [ { name = "circle", numberOfSides = 0, isFilled = True, colorValue = "red", strokeWidth = 2 }
    , { name = "triangle"
      , numberOfSides = 3
      , isFilled = False
      , colorValue = "blue"
      , strokeWidth = 1
      }
    ]

Question 5 - Multi-line block comments are re-indented

The body of a multi-line block comment is re-indented from the comment's own
structure: the shallowest body line is aligned three columns past the {-
(under the first character after {- ), and any deeper line keeps its extra
indentation relative to that.

This is straight-forward. However the body was written:

config =
        {- the body of this block comment
              spans several lines
           and is re-indented -}
        42

it comes out anchored to the {-, independent of the original columns:

config =
    {- the body of this block comment
          spans several lines
       and is re-indented -}
    42

However, there are cases where the 2nd line (and beyond) of the multi-line
comment start at a column before the "{-".
Here the opener is indented but the body lines start flush at the left margin:

config =
        {- this comment opener is indented
but the body lines are written flush at the left margin
   and this one is a little deeper -}
        42

The body is still pulled in and anchored three columns past the {-, with the
deeper line kept deeper:

config =
    {- this comment opener is indented
       but the body lines are written flush at the left margin
          and this one is a little deeper -}
    42

Is this what we want? or, do we keep the comments at the absolute starting
column position at which the author wrote them?

Question 6 - Binop chains break strangely

Here is something I just noticed.
A binop chain that overflows breaks the first operand(s) onto their own lines but
then leaves the remaining operands crammed onto one line, with operators at the
seed column (not indented):

binopChain =
    operandOne
    + operandTwo
    + operandThree + operandFour + operandFive + operandSix + operandSeven + operandEight

I think this should change to look more like how a long function call wraps:

binopChain =
    operandOne + operandTwo operandThree + operandFour + operandFive + operandSix
        + operandSeven + operandEight

or

binopChain =
    operandOne + operandTwo operandThree + operandFour + operandFive + operandSix +
        operandSeven + operandEight

Where does the binop go?

[robinheghan]

A lot of people coming to Gren probably has experience with elm and elm-format. The core packages in Gren were formatted with elm-format before I ported them over. I think it'd be best to stick with elm-format rules unless there are good reasons not to.

elm-format follows Elm's official style guide. It also tries to format code in such a way to minify diffs between commits. This has gathered some criticism, since Elm code ends up taking a lot of vertical space, but I believe most people like the formatting of it.

Question 1 - Number of spaces per indentation

My personal preference here is 2, but for the reasons stated above I'll go with 4, unless there are several people in the Gren community that would like to challenge this.

Question 2 - Page Width

80, as per the Elm's style guide.

I tend to have 3-4 open tabs on my screen, and 80 suits that quite nicely.

Question 3 - Multi-line "if" predicates

If it's impossible to keep if and then on the same line, then I'd prefer the code to be formatted like:

if
  bool1 && bool2 && bool3
then
  whatToDo

Question 4 - Indentation of nested brackets

This is actually one of the reasons why I preferred 2-space indents as standard when the discussion was happening for elm-format. It makes this particular case follow standard rules instead of being an edge case.

That said, I think the first example you provide looks good 👍

Regarding your second example, we should strive to format each value in an array in the same way. If one record is broken over multiple lines, then all of them should be.

Question 5 - Multi-line block comments are re-indented

I think all the lines should see the same level of indentation changes. If the first line of a multi-line comment is de-indented two spaces, then all other lines should also be de-indented two spaces. Otherwise, I think we should strive the keep the comment as close to what the user originally wrote as possible.

Question 6 - Binop chains break strangely

Binop chains should either be all on one line, or each part of the chain should be on a line of its own.

either =
  a + b + c + d

or =
 a
   + b
   + c
   + d

[gilramir]

I was able to fix almost everything.
Regarding Question 4 - Indentation of nested brackets
Yes, I think the example nesting looks good too and have kept it.

But for your follow-up comment, "If one record is broken over multiple lines, then all of them should be.", I don't have that working yet. I made one attempt, but it turned out to be non-idempotent. I have another idea, which I will take a look at next week.

But I'll release the current batch of changes now so people can try them.

Long "if" predicates

Oh also, I did implement the "if/then" alignment as per:

if
  bool1 && bool2 && bool3
then
  whatToDo

But I also noticed that we need to decide how to render a very long "if" predicat that has binops in it. Should it go all the way across, and then indent on the next line, or should it become vertical, like so many other things do?
e.g., a really long predicate could be rendered as:

if
    userIsActive && accountHasCredit && not isSuspended && withinQuota
        && verified
then
    showDashboard x

or as

if
    userIsActive
        && accountHasCredit
        && not isSuspended
        && withinQuota
        && verified
then
    showDashboard x

bindings with just one literal as the body

Please note a couple things in my README.md once I release it; I have an experiment going on with functions whose body is a simple literal, keeping them on the same line:

version = "1.0.0"     -- literal
answer = 42           -- literal
handler = onClick     -- bare variable
name = model.user.name -- field access
double n = 2          -- a function whose body is a literal also stays inline

vs bodies with anything else:

double : Int -> Int
double n =
    n * 2

makePoint x y =
    { x = x, y = y }

I thought I would try this, but I don't know if it's desirable or not.

Binops line breaks based on precedence

Also note the "Binary operators" section of the README.md; in the multi-line mode, the formatter is organizing the line splits based on precedence of the operators, which I think makes it easy to understand:

score =
    baseScore
        + bonusPoints * multiplier
        - penaltyAmount
        + streakBonus * weight

Again, maybe we want this, or maybe not.

[robinheghan]

Long "if" predicates: I think the last example looks best

bindings with just one literal as the body: I believe I prefer keeping literals on a separate line, but if anyone else has a strong preference I'd be open to listen.

Binops line breaks based on precedence: A problem that I have with binops is that I can't, for the life of me, remember the operator precedence, so this kind of line breaking seems arbitrary to me. I'm aware that this is a me problem 😂

But it does raise an interesting case with operator chains in general: parenthesis.

func
  |> second
  |> (myVal |> wrapper)
  |> third

How is this handled?

[gilramir]

When I feed it this input:

module Example exposing ( foo )

foo =
    func
    |> second |> (myVal |> wrapper) |> third

The output is:

module Example exposing ( foo )


foo =
    func
        |> second
        |> (myVal |> wrapper)
        |> third