Add documentation on why we don't support "hanging indent" style

[Yunuuuu]

I would love to something like this:

fn <- function(long_long_long_long_long_long_long_arg1,
               long_long_long_long_long_long_long_arg2) {
    
}

But air gave me this:

fn <- function(
    long_long_long_long_long_long_long_arg1,
    long_long_long_long_long_long_long_arg2
) {
}

[DavisVaughan]

In Air we do not allow the "hanging indent" style in your first example in function definitions or function calls.

We haven't added the official docs about this, but we have old docs in here about this:
https://github.com/posit-dev/air/blob/main/docs-old/formatter.md#function-definition-styles

Notably, hanging indent is bad for accessibility if you switch to using tabs:
https://github.com/posit-dev/air/blob/main/docs-old/formatter.md#mixing-tabs-and-spaces

It also makes it significantly more complex to have 3 layouts (flat, hanging, expanded) in the formatter. I don't think our persistent line breaks feature would be possible if we supported this

[DavisVaughan]

Keeping open so we can add docs about it

[juliasilge]

The main thing that convinced me I don't actually want hanging indents is rainbow tabs 🌈 😆

[DavisVaughan]

TRUE

[Yunuuuu]

Or if it could be possible to skip a single line like styler:

fn <- function(long_long_long_long_long_long_long_arg1,    # fmt: skip
               long_long_long_long_long_long_long_arg2) {  # fmt: skip
    # the inner block should be formated
    if (    TRUE &&        FALSE) {
}
}

[DavisVaughan]

# fmt: skip applies to nodes not lines, so in this case # fmt: skip is getting attached to long_long_long_long_long_long_long_arg1 itself (imagine it was 1+1, that would not get formatted).

But even so, I don't think we would encourage doing this. If you want to use Air, then I'd likely to respectfully encourage you to give this new expanded format a chance. For me (who has been doing hanging indent for years), it started to feel natural very quickly. It is also extremely similar to how many other languages format their function signatures, making it ever so slightly easier to cross between languages.

I also think it makes your example easier to read

fn <- function(
  long_long_long_long_long_long_long_arg1,
  long_long_long_long_long_long_long_arg2
) {
  # the inner block should be formated
  if (TRUE && FALSE) {
  }
}

i.e. your eyes scan straight down the page when reading the function from top to bottom, rather than having to look off to the right a little to read the arguments and then move back to the left to read the body of the function. This is obviously all a little subjective and hand wavy but the overall indentation level of the styled code is something we think about for reasons like this one.

[Yunuuuu]

Thanks for the clarification! I'll certainly give it a shot and see how it feels in practice. The current styler package is too slow for large files.

[strengejacke]

Skipping lines from formatting would be great, if you don't plan hanging indents.

In general, I don't use hanging indents inside functions, but I'd really +1 this request. The function definition should be hanging indent, it clearly separates the function header from the body of that function.

[strengejacke]

Let me repost my screenshot from the discussion forum. Only for function headers, having hanging indents would be great:

This is also not related to "rainbow" brackets, since you have no nesting in a function header.

[jennybc]

This is related to rainbow tabs or indents (a lot of us use indent-rainbow in VS Code and Positron):

[DavisVaughan]

You'd have to put # fmt: skip after every line, and that doesn't seem sustainable even if we wanted to support that particular use case.

The function definition should be hanging indent, it clearly separates the function header from the body of that function

As discussed earlier we believe that hanging indent is bad for accessibility (the rainbow parens below are a visual representation of how it is bad). The ) { is a nice way to separate the signature from the body and is the convention that many other languages use as well.

This is also not related to "rainbow" brackets, since you have no nesting in a function header.

Sure you do!

With air indentation

With hanging indentation

And here's what happens if join_rows() was called join_rowss() instead (one more letter). It completely breaks the indentation level. Before, we got lucky that the number of characters in join_rows <- function( happened to divide by 2 evenly.

If we look past the fact that many of us have used hanging indent for years, it doesn't really make much sense from the perspective of an automatic formatter that typically only bumps indentation level out or in by one level at a time.

[strengejacke]

ok, I see the point. Wasn't thinking of rainbow indents (couldn't imagine someone is using this ;-)).
Maybe in the future, it is possible to skip sections from formatting, like styler on/off (so you don't need it on every line).

Is it somewhere documented what the "scope" of formatting is when you format a selection? Depending on where I am inside / outside brackets, the scope/range of the formatted region is going beyond the exact selection. Sometimes, I "accidentally" reformat my hanging indents from the function header.