Style guide for Shrubbery/Rhombus

[sorawee]

Line width

The Racket style guide sets the line width limit to 102 characters (read justification here).

I disagree with this limit. It causes side-by-side diff really difficult to read, at least on my 13-inch laptop (which as I understand is a very common size). Personally, I think that 80 characters would make more sense.

Indentation

The most common indentation size that I have seen so far is 2.

Meta discussion on formatting

For most programming languages, there are multiple ways to format code. These multiple ways mostly offer trade-off between increasing the width and increasing the height. Shrubbery/Rhombus is no different.

It may be useful to think that there is a fallback layout for each code unit. Other layouts are "nicer", but they are not always applicable due to constraints. As a concrete example, in Racket, a function application has the following fallback layout:

(abc
 def
 ghi)

(abc def ghi) and

(abc def
     ghi)

would be more desirable, as long as these layouts don't cause the code to go beyond the line width. Furthermore (abc def ghi) would have an additional constraint that they should be flat (has height 1). E.g., we probably should not write

(foo (+ fooooooooo
        barrrrrrrrrrr) (+ fooooooooo
                          barrrrrrrrrrr))

Shrubbery formatting

Following is a proposed style guide for a general Shrubbery (which is uninterpreted). For Rhombus (where Shrubbery is interpreted), formatting could be different based on contents. The guide is written with Shrubbery pretty printing in mind. I.e., it's intended to be the specification for the pretty printer.

Block formatting

In general, a block's body could be formatted in two ways:

// (a)
ab cd: 
  ef
  gh

// (b)
ab cd: ef
       gh

The layout (a) is the fallback one.

In @mflatt's talk, he presented the code:

val area: fun (radius):
            pi * radius * radius

and then commented that he actually doesn't like this layout; a prettier layout would be:

val area: 
  fun (radius):
    pi * radius * radius

I propose the following rule which captures the desired output:

If the first children of a block is directly another block, the layout (a) is preferred

Note that this rule, as it is currently stated, does not apply to:

val area: (fun (radius):
             pi * radius * radius)

because the first children is a parens, not a block.

Paren-like formatting

There are three possible layouts:

// (a)
something {
  a, 
  b, 
  c,
}

// (b)
something {a, b, c}

// (c)
something { a,
            b,
            c }

Layout (a) is the fallback one.

Layout (b) is only applicable when "arguments" are all flat (height = 1). This is to reflect that:

something { a, foo:
                  bar, b }

is probably not a great layout to use.

Group formatting

Newlines and indents could be uniformly inserted before infix operators

// (a)
aaa xxx
  + bbb yyy
  + ccc zzz

// (b)
aaa xxx + bbb yyy + ccc zzz

(a) is the fallback one. (b) is only applicable when it is flat.

Alts formatting

There are two ways to format alts

// (a)
data Color
| red
| green
| blue

// (b)
data Color | red | green | blue

(a) is the fallback layout. (b) is only applicable when it is flat.

Operator formatting

There are three layouts:

• Prefix: no space between the operator and operand.
• Postfix: no space between the operator and operand.
• Infix: has two sublayouts: either one space surrounding the operator, or no space surrounding the operator, consistently throughout the file.

Exception: when an infix operator appears as the first token in a line, there should be no space on the left of the operator.

In the pretty printer, when the raw information is not available, an extra operator table could be provided to supply this information.

Others

; and «» are generally not recommended.

Question

Another possible layout is "fit as many as possible in each line". For specific forms in Rhombus, I guess it could be a good idea. But is it a good idea for general Shrubbery?

foo(arg1, arg2, arg3, |||
    arg456, arg78,    |||
    arg1234, arg5)    |||

aaaaa + bbbbb + ccccc |||
  + ddddd + eeeee     |||

data Color | red | green  |||
           | blue | brown |||

This layout is only applicable when it is flat.

[samdphillips]

This seems good to me. I think seeing my hand-formatted code vs. the code formatter would be useful.

[mflatt]

For what it's worth, these rules also look good to me.