Alignment versus non-aligning indentation

[joshtriplett]

For a variety of cases, we should decide between alignment or non-aligning indentation. When breaking a line, should the item on the next line align with the item, or just have an additional level of indentation compared to the previous line? For instance:

fn alignment(arg: T,
             arg2: T2)

fn indentation(
        arg: T,
        arg2: T2)

let aligned = (value1
             + value2);
let indented = (
        value1
        + value2);
let indented2 = (
        value1
        + value2
);

let structval_aligned = S { field: value,
                            field2: value };

let structval_indented = S {
        field: value,
        field2: value,
};

function_call_aligned(param1,
                      param2);
function_call_indented(
    param1,
    param2);

This seems mostly orthogonal to indentation size, line length, and where exactly to break various types of lines.

I would propose avoiding alignment as a general principle. While alignment can sometimes improve readability, it produces significantly more noise in version control, since changes to one line can ripple outward into spacing changes on many lines. Alignment also tends to more quickly drift to the right edge of the screen, and produces worse results when wrapping lines close to a line-length limit.

In many cases, breaking the line and indenting before the first item provides the same benefit without the corresponding problem.

[strega-nil]

I agree, obviously :3

[nrc]

The terms we use in Rustfmt (which were terms of art elsewhere) are visual indent and block indent.

For block indent, there are two variations - either using a newline before the first argument or not:

fn some_function(arg1: Type1,
    arg2: Type2);

fn some_function(
    arg1: Type1,
    arg2: Type2);

We might want to consider some cases separately - currently Rustfmt use block indenting for struct literals and field/method chains, and visual indenting elsewhere. This brings up the issue of mixing, specifically, if you have a block indented item nested inside a visually indented item, do you block indent from the visual indent, or from the previous block indent?

In general, we must consider nesting carefully here.

I think we should probably decide on some of our guiding principles before dwelling too long here - this is a big and far-reaching decision and I think which choice we take comes down to how we prioritise issues:

@joshtriplett laid out arguments in favour of block indentation. It is also easier to implement and has fewer edge cases with nesting, etc.

However, visual indentation is (IMO) vastly more aesthetic in most situations, usually easier to read, and uses less vertical space (if adopting the second variation of block indentation).

It seems to me impossible to make a purely objective trade-off between these advantages, and so we must decide on the relative principle of our guiding principles first.

[solson]

For myself, visual indent is more frustrating to read both in general and because it leads rustfmt into pathological edge cases more often. So, for me it's all downsides, but it seems that most of us at least agree that block indent has a simplicity advantage.

Of the guiding principles that have been discussed so far, I think these are the ones where block indent wins uncontroversially:

• preventing right-ward drift
• preserving diffs / compatibility with version control practices
• ease of manual formatting
• ease of automatic formatting for editors not using Rustfmt
• ease of implementation
• ease of re-implementation in other formatting tools
• simplicity of formatting rules
• simplicity for code generators outputting Rust code

And these are the ones where visual indent wins uncontroversially:

• minimising vertical space

And these are the subjective ones I think could be argued both ways:

• readability
• scan-ability
• consistency with formatting used in other languages
• aesthetics

Many of the principles I listed for block indent are saying nearly the same thing, so a simple bullet point count score isn't fair, but I think it's still safe to say that block indent has more objective pros.

Unless a strong argument can be made that the subjective advantages of visual indent outweigh the advantages of block indent for the majority of the community, it seems logical to favour block indent.

[nrc]

Of the guiding principles that have been discussed so far

I think this is maybe jumping the gun a little bit - we should decide first which principles are important to us, and then make a decision here. The principles suggested so far are just suggestions, it may be that we decided that they should not be taken into account. And, as you point out, we should probably coalesce some of these principles.

[solson]

@nrc Yeah, that's fair. I think putting them to the test like this might help us decide which are important, but it's good to note these are just suggestions for principles at this point.

[briansmith]

I would propose avoiding alignment as a general principle. While alignment can sometimes improve readability, it produces significantly more noise in version control, since changes to one line can ripple outward into spacing changes on many lines. Alignment also tends to more quickly drift to the right edge of the screen, and produces worse results when wrapping lines close to a line-length limit.

In many cases, breaking the line and indenting before the first item provides the same benefit without the corresponding problem.

The policy I've seen for clangformat in Google projects I work on seems to be "Prefer to align wrapped values unless that would cause the wrapped result to have more lines." That is, column width > minimum number of lines > aligned in terms of priorities. I think this makes the most sense.

[strega-nil]

Another argument in favor of block indent: visual indents is poor for accessibility, at least how it's currently used in rustc (@camlorn from irc):

camlorn eddyb: I have to specifically put the cursor there, read off the column number, then align it by counting spacces. [sic]

(note: camlorn is blind)

[retep998]

For block indent, there are two variations - either using a newline before the first argument or not:

@nrc there is another variation where the ending parentheses goes on a new line, and is the style that I prefer and use.

fn some_function(
    arg1: Type1,
    arg2: Type2,
);

I remain strongly opposed to any attempts at making aligned indentation the standard style.

[joshtriplett]

@retep998 In languages that allow a trailing comma on the last item, that's my preferred style as well for anything that doesn't fit comfortably on one line.

[retep998]

I prefer my style because it is a very consistent style. Imagine if we formatted structs like this:

struct Foo { field1: Type1,
             field2: Type2 }
struct Foo { field1: Type1,
    field2: Type2 }
struct Foo {
    field1: Type1,
    field2: Type2 }

I don't see anyone clamoring to align structs like that, so why should we align functions like that?

[joshtriplett]

@retep998 I think we're in complete agreement here. 😄

[ahicks92]

Not going to be very opinionated here, as I'm probably the sole blind contributor to the project and am capable of differentiating between what is good for me and what is good for the majority. That said I like the block style, though I'm not sure why the original comment is using 8 spaces.

The specific problem with aligning with the left paren as a blind person is that you can't tell if it's wrong without an explicit check. I put it right the first time. Then the function's name changes or what have you, and there's nothing reminding me to fix it. Then the PR gets a comment about it and I'm annoyed because that's annoying and also to me it's all senseless anyway.

Very few blind programmers use Braille displays for reading code. The way indentation is exposed (if you bother to have it on) is by announcing the number of spaces at every change. Python is accessible, but indentation isn't about being pretty, it's about being semantical, for lack of a better word. I use it because it's helpful in getting closing braces right and sighted people will flat out refuse to read code without it in some cases, but otherwise I wouldn't even bother with it.

I also miss things like spaces after // or ///, spaces around ->, etc. And then there's the ones I absolutely don't mean to miss like spaces before {. And the ones that make no intuitive sense to me, like (.. vs. { .. }.

I suppose it would be worse if I had always been fully blind, but I had enough that I was able to get some idea of why code layout is how it is. Otherwise, this conversation would probably be going quite, quite differently...

[joshtriplett]

@camlorn To me, that's a substantial argument in favor of block indentation and against visual indentation. I appreciate your feedback and perspective.

Even when it's possible to see the misaligned visual alignment at a glance, people often send patches that don't update the alignment or that copy/pastes the alignment for another function, and often that issue gets missed, resulting in code that no longer has any sensible alignment. Together with the point that it's even more painful to deal with that alignment without visual feedback, that makes me even more inclined to avoid visual alignment.

I've also proposed in #4 that we take non-visual interfaces such as speech into account as a guiding principle. That doesn't mean it'll always be the highest priority consideration, but we should always take it into account.

[briansmith]

@camlorn Isn't rustfmt itself an accessibility tool that obviates the need to check the formatting of code before submitting patches for review? That is, you'd just cargo fmt before git add and git commit and not need to worry at all? That is, as far as screen readers are concerned, it seems like the onus should be on the project to ensure that cargo fmt works correctly, and not necessarily on the default styling rules. Otherwise, if we optimized the default rules for screen readers then I think we'd have, for example, one line per statement, no matter how long it is.