gleam format principles

[inoas]

lpil: Let's start collecting examples of formatter behaviour we don't like / I'd generally like to improve the format

https://discord.com/channels/768594524158427167/768594524158427170/972580646771904632

[inoas]

Should here means: I wish or I'd prefer. I have no authority/say in how gleams formatting should in the end act like.

1. Idempotency of adding and removing simple comments: If I add and remove // in a long test with multiple pipes the formatting I gave it is then removed, as new lines do not get comments between them. I have to manually insert // between two outcommented blocks of code to keep the spacing which is tedious. Also new // blocks try to glue to the next statement.

  value
  |> io.debug

  value
  |> dynamic.from
  |> io.debug

  value
  |> dynamic.from
  |> dynamic.classify
  |> io.debug

becomes

  // value
  // |> io.debug
  // value
  // |> dynamic.from
  // |> io.debug
  value
  |> dynamic.from
  |> dynamic.classify
  |> io.debug

becomes

  value
  |> io.debug
  value
  |> dynamic.from
  |> io.debug
  value
  |> dynamic.from
  |> dynamic.classify
  |> io.debug

2. When writing /// test inside a function it magically moves it below the function. It should IMHO either not compile or move it to the top of the function.

3. When writring short pipes they should not add line breaks during pipeing IMHO, this should IMHO not add auto breaks to all pipe operators in a statement if:

   1. a piped statement is shorter than 80 chars including left padding AND
   2. a piped statement has equal to or less than 4 parts (initial value, 3 pipe operators)
      If piping adds line breaks it should add them to all pipe operators of the same statement.

4. Multiple pipe statements should add a margin line in between if they go into multiple lines to improve readablility:

Bad examples:

  value
  |> foo.bar
  |> quux.batz
  |> kek.lul
  |> more.here
  value2
  |> foo.bar
  |> quux.batz
  |> kek.lul
  |> more.here

Good examples:

  value
  |> foo.bar
  |> quux.batz
  |> kek.lul
  |> more.here

  value2
  |> foo.bar
  |> quux.batz
  |> kek.lul
  |> more.here

  let value1 = value1
  |> foo.bar
  |> quux.batz
  |> kek.lul
  |> more.here

  let value2 = value2
  |> foo.bar
  |> quux.batz
  |> kek.lul
  |> more.here

So to summarize:

1. If a statement is short it should go on one line and not force margins.
2. If a statement is long it should be broken across multiple lines and force margin top/bottom.
3. any horizontal margins should collapse to a single margin line like they do in HTML/CSS.

[lpil]

Idempotency of adding and removing simple comments

Great suggestion. I shall make an issue for preserving spaces between comments.

When writing /// test inside a function it magically moves it below the function. It should IMHO either not compile or move it to the top of the function.

What is the use case for using the documentation comment inside of a function?

When writring short pipes they should not add line breaks during pipeing

Sounds good, I'll make an issue for that one too

[inoas]

What is the use case for using the documentation comment inside of a function?

Documenting anonymous functions.
If that's not valid it should move to the top or throw an error, moving to the bottom may mean you never see that it moved there until after you git commit.

[lpil]

In that case you would use a regular comment. The triple slash comment is for the HTML documentation, and that does not do anything for values such as anonymous functions.

[inoas]

Okay, but then it should be moved ontop of the function head, I suppose?

[inoas]

When autoformatting Elixir I noticed that it removes double margin lines above and below comments. That's a good feature IMHO: Leaving those comments as they are except for the collapse of possible margins to 1.

[sporto]

My personal wish is that the formatter would respect line breaks I add (or allow me to change the line width).

I work with several vertical splits. The line width that the formatter assumes is often too wide for my splits. As the formatter joins lines I often see these lines wrapping, making the formatted code confusing.

For example, the way I would like to format:

pub service(
  handler: Handler,
  context: Context
) {
  ...
}

After the formatter joins this, I end up visually with this:

pub service(
  handler: Handler, context:
Context) {
  ...
}

Places where I often see this issue:

• Function signatures
• Case expressions (will like to drop the part after ->)
• List

[lpil]

Totally. There's an issue for that here #1117

[inoas]

or allow me to change the line width

I would like that as a per-project setting so that if I run gleam format all source is the same style.

[lpil]

There will be no settings for the formatter I'm afraid

[superhawk610]

The formatter will add an empty line at the top of a document that contains only simple // comments.

For example, this

// foo
// bar

formats to

// foo
// bar

[lpil]

This is a bug! Please open an issue

[superhawk610]

Done! #1640

[inoas]

Some preferences:

• if any case clause wraps onto a new line all case clauses then should for consistency.

• for multiple if parts in a case clause if these need to break because of line length, then curley braces for grouping should be respected (indentation?) andd the boolean operator to be on the new line not the old line.