New tall style: Automated trailing commas and other formatting changes

[munificent]

TL;DR: We're proposing a set of style changes to dart format that would affect about 10% of all Dart code. We want to know what you think.

The main change is that you no longer need to manually add or remove trailing commas. The formatter adds them to any argument or parameter list that splits across multiple lines and removes them from ones that don't. When an argument list or parameter list splits, it is formatted like:

longFunction(
  longArgument,
  anotherLongArgument,
);

This change means less work writing and refactoring code, and no more reminding people to add or remove trailing commas in code reviews. We have a prototype implementation that you can try out. There is a detailed feedback form below, but you can give us your overall impression by reacting to the issue:

• 👍 Yes, I like the proposal. Ship it!
• 👎 No, I don't like the proposal. Don't do it.

We have always been very cautious about changing the formatter's style rules to minimize churn in already-formatted code. Most of these style rules were chosen before Flutter existed and before we knew what idiomatic Flutter code looked like.

We've learned a lot about what idiomatic Dart looks like since then. In particular, large deeply nested function calls of "data-like" code are common. To accommodate them, the formatter lets you partially opt into a different formatting style by explicitly authoring trailing commas in argument and parameter lists. I think we can do better, but doing so would be the largest change we've ever made to the formatter.

I'm starting this change process to determine whether or not it's a change the community is in favor of. Details are below, but in short, I propose:

• The formatter treats trailing commas in argument lists and parameter lists as "whitespace". The formatter adds or removes them as it sees fit just as it does with other whitespace.

• When an argument or parameter list is split, it always uses a "tall" style where the elements are indented two spaces, and the closing ) is moved to the next line:

  longFunction(
    longArgument,
    anotherLongArgument,
  );

• The formatting rules for other language constructs are adjusted to mesh well with argument and parameter lists formatted in that style. For example, with that style, I think it looks better to prefer splitting in an argument list instead of after = in an assignment or variable declaration:

  // Before:
  var something =
      function(argument);
  
  // After:
  var something = function(
    argument,
  );

The overall goal is to produce output that is as beautiful and readable as possible for the kind of code most Dart users are writing today, and to give you that without any additional effort on your part.

Background

The formatter currently treats a trailing comma in an argument or parameter list as an explicit hand-authored signal to select one of two formatting styles:

// Page width:               |

// No trailing comma = "short" style:
noTrailingComma(
    longArgument,
    anotherLongArgument);

// Trailing comma = "tall" style:
withTrailingComma(
  longArgument,
  anotherLongArgument,
);

A trailing comma also forces the surrounding construct to split even when it would otherwise fit within a single line:

force(
  arg,
);

The pros of this approach are:

• Before Dart allowed trailing commas in argument and parameter lists, they were formatted in the short style. Having to opt in to the tall style by writing an explicit trailing comma, avoids churn in already-formatted code.

• Users who prefer either the short or tall style can each have it their way.

• If a user wants to force an argument or parameter list to split that would otherwise fit (and they want a tall style), they can control this explicitly.

The cons are:

• The short style is inconsistent with how list and map literals are formatted, so nested code containing a mixture of function calls and collections—very common in Flutter code—looks inconsistent.

• If a user wants the tall style but doesn't want to force every argument or parameter list to split, they have no way of getting that. There's no way to say "split or unsplit this as needed, but if you do split, use a tall style".

  Instead, users who want a tall style must remember to manually remove any trailing comma on an argument or parameter list if they want to allow it fit on one line. This is particularly painful with large scale automated refactorings where it's infeasible to massage the potentially thousands of modified lists to remove their trailing commas.

  Worse, there's no way to tell if a trailing comma was authored to mean "I want to force this to split" versus "I want this to have tall style", so anyone maintaining the code afterwards doesn't know whether a now-unnecessary trailing comma should remain or not.

• Users must be diligent in maintaining trailing commas in order to get the same style across an entire codebase.

  The goal of automated formatting is to get users out of the business of making style choices. But the current implementation requires them to hand-author formatting choices on every argument and parameter list.

  For users who prefer a tall style, they must be careful to add a trailing comma and then reformat whenever an existing argument or parameter list that used to fit on one line no longer does and gets split. By default, as soon as the list overflows, it will get the short style.

  Again, this is most painful with large scale refactorings. A rename that makes an identifier longer could lead to thousands of argument lists splitting. If those are in code that otherwise prefers a tall style, the result is a mixture of short and tall styles.

• The rest of the style rules aren't designed to harmonize with tall style argument and parameter lists since they don't know whether nearby code will use a short or tall style. There's no way to opt in to a holistic set of style rules designed to make all Dart code look great in that style.

  This leads to a long tail of bug reports where some other construct clearly doesn't look good when composed with tall-style argument and parameter lists, but there's not much we can do because the construct does look fine when composed with short style code.

I believe the cons outweigh the pros, which leads to this proposal.

Proposal

There are basically three interelated pieces to the proposal:

Trailing commas as whitespace

Trailing commas in argument and parameter lists are treated as "whitespace" characters and under the formatter's purview to add and remove. (Arguably, they really are whitespace characters, since they have zero effect on program semantics.)

The rule for adding and removing them is simple:

• If a comma-separated construct is split across multiple lines, then add a trailing comma after the last element. This applies to argument lists, parameter lists, list literals, map literals, set literals, records, record types, enum values, switch expression cases, and assert arguments.

  (There are a couple of comma-separated constructs that don't allow trailing commas that are excluded from this like type parameter and type argument lists.)

• Conversely, if the formatter decides to collapse a comma-separated construct onto a single line, then do so and remove the trailing comma.

The last part means that users can no longer hand-author a trailing comma to mean, "I know it fits on one line but force it to split anyway because I want it to." I think it's worth losing that capability in order to preserve reversibility. If the formatter treated trailing commas as user-authored intent, but also inserted them itself, then once a piece of code has been formatted once, it can no longer tell which commas came from a human and which came from itself.

Always use tall style argument and parameter lists

If a trailing comma no longer lets a user choose between a short or tall style, then the formatter has to choose. I think it should always choose a tall style.

Both inside Google and externally, the clear trend is users adding trailing commas to opt into the tall style. An analysis of the 2,000 most recently published Pub packages shows:

-- Arg list (2672877 total) --
1522870 ( 56.975%): Single-line  ===========================
 455266 ( 17.033%): Empty        =========
 347996 ( 13.020%): Tall         =======
 208585 (  7.804%): Block-like   ====
 137682 (  5.151%): Short        ===
    478 (  0.018%): Other        =

The two lines that are relevant here are:

-- Arg list (2672877 total) --
 347996 ( 13.020%): Tall         =======
 137682 (  5.151%): Short        ===

Of the argument lists where either a short or tall style preference can be distinguished, users prefer the tall style ~71% of the time, even though they have to remember to hand-author a trailing comma on every argument list to get it.

Block-like argument lists

I've been talking about "short" and "tall" argument lists, but there are actually three ways that argument lists get formatted:

// Page width:               |

// Short style:
longFunctionName(
    veryLongArgument,
    anotherLongArgument);

// Tall style:
longFunctionName(
  veryLongArgument,
  anotherLongArgument,
);

// Block style:
longFunctionName(() {
  closure();
});

The third style is used when some of the arguments are function expressions or collection literals and formatting the argument list almost as if it were a built-in statement in the language looks better. The most common example is in tests:

main() {
  group('Some group', () {
    test('A test', () {
      expect(1 + 1, 2);
    });
  });
}

This proposal still supports block-style argument lists. It does somewhat tweak the heuristics the formatter uses to decide when an argument list should be block-like or not. The current heuristics are very complex, subtle, and still don't always look right.

Format the rest of the language holistically to match

The set of formatting rules for the different language features were not designed to make each feature look nice in isolation. Instead, the goal was a coherent set of style rules that hang together and make an entire source file clear and readable.

Those rules currently assume that argument and parameter lists have short formatting. With this proposal, we also adjust many of those other rules and heuristics now that we know that when an argument or parameter list splits, it will split in a tall style way.

There are many of these mostly small-scale tweaks. Some examples:

• Prefer to split in the initializer instead of after "=":

  // Page width:               |
  
  // Before:
  var something =
      function(argument);
  
  // After:
  var something = function(
    argument,
  );

• Less indentation for collection literal => member bodies:

  // Page width:               |
  
  // Before:
  class Foo {
    List<String> get things => [
          'a long string literal',
          'another long string literal',
        ];
  }
  
  // After:
  class Foo {
    List<String> get things => [
      'a long string literal',
      'another long string literal',
    ];
  }

• Don't split after => if a parameter list splits:

  // Page width:               |
  
  // Before:
  function(String parameter,
          int another) =>
      otherFunction(
          parameter, another);
  
  // After:
  function(
    String parameter,
    int another,
  ) => otherFunction(
    parameter,
    another,
  );

I used the Flutter repository as a reference, which uses tall style and has been very carefully hand-formatted for maximum readability, and tweaked the rules to follow that wherever I could. Many of the changes are subtle in ways that are hard to describe here. The best way to see them in action is to try out the prototype implementation, described below.

Risks

While I believe the proposed style looks better for most Dart code and makes users' lives simpler by not having to worry about maintaining trailing commas, this is a large change with some downsides:

Churn

Formatting a previously formatted codebase with this new style will cause about 10% of the lines of code to change. That's a large diff and can be disruptive to codebases where there are many in-progress changes.

Migrating to the new style may be painful for users, though of course it is totally automated.

Users may dislike the style

Obviously, if a large enough fraction of users don't want this change, we won't do it, which is what the change process aims to discover. But even if 90% of the users prefer the new style, that still leaves 10% who now feel the tool is worse than it was before.

Realistically, no change of this scale will please everyone. One of the main challenges in maintaining an opinionated formatter that only supports one consistent style is that some users are always unhappy with it. At least by rarely changing the style, we avoid drawing user attention to the style when they don't like it. This large, disruptive change will make all users at least briefly very aware of automated formatting.

Two configurable styles

An obvious solution to user dislike is to make the style configurable: We could let you specify whether you want the old formatting rules or the new ones. The formatter could support two separate holistic styles, without going all the way towards full configurability (which is an anti-goal for the tool).

There are engineering challenges with this. The internal representation the formatter uses to determine where to split lines has grown piecemeal over the formatter's history. The result is hard to extend and limited in the kind of style rules it can represent. When new language features are added it's often difficult to express the style rules we want in terms that the internal representation supports. Many long-standing bugs can't be fixed because the rule a user wants can't be modeled in the current representation.

This became clear when working on a prototype of the proposal. Getting it working was difficult and there are edge cases where I can't get it to model the rules I want.

If this proposal is accepted and we make large-scale changes to the formatting rules, we intend to take the opportunity to also implement a better internal representation. That's a large piece of work for a tool that generally doesn't have a lot of engineering resources allocated to it.

We don't have the bandwidth during this change to write a new IR, a new set of style rules and migrate the old style rules to the new IR. There may be old rules the new IR can't represent well.

We could keep the old IR around for the old style and use the new IR only for the new style. But going forward, we don't have the resources to maintain two sets of style rules and two separate internal representations, one for each. Every time a new language feature ships, the formatter needs support for it. Bugs would have to get fixed twice (or, more likely, only fixed for one style).

We might be able to temporarily support both styles in order to offer a migration period. But we don't have the resources to support both styles in perpetuity. We would rather spend those resources supporting one style really well instead of two styles poorly.

Evaluation

This is a large style change. Because the formatter is deliberately opinionated and non-configurable, it will affect all users of dart format. That means it's important to make sure that it's a good change in the eyes of as many users as possible. We can't please everyone, but we should certainly please a clear majority.

To that end, we need your feedback. That feedback is most useful when it's grounded in concrete experience.

Prototype implementation

To help with that, we have a prototype implementation of the new style rules. The prototype has known performance regressions and doesn't get the style exactly right in some cases. But, for the most part, it should show you the proposed behavior.

Diff corpus

We ran this prototype on a randomly selected corpus of code, which yields the resulting diff. This shows you how the new formatting compares to the behavior of the current formatter. Keep in mind that a diff focuses your attention on places where the style is different. It doesn't highlight the majority of lines of code that are formatted exactly the same under this proposal as they are today.

Running it yourself

To get a better sense of what it feels like to use this proposed behavior, you can install the prototype branch of the formatter from Git:

$ dart pub global activate \
    --source=git https://github.com/dart-lang/dart_style \
    --git-ref=flutter-style-experiment

You can run this using the same command-line options as dart format. For example, to reformat the current directly and its subdirectories, you would run:

$ dart pub global run dart_style:format .

To format just a single file, example.dart, you would run:

$ dart pub global run dart_style:format example.dart

Give us your feedback

Once you've tried it out, let us know what you think by taking this survey. You can also reply directly on this issue, but the survey will help us aggregate the responses more easily. We'll take the survey responses and any comments here into account and try our best to do what's right for the community.

After a week or, to give people time to reply, I'll update with what we've learned.

This is an uncomfortably large change to propose (and a hard one to implement!), so I appreciate your patience and understanding while we work through the process.

Thank you!

– Bob

[suragch]

I like it. I manually add trailing commas a lot in just the style that this proposal would handle automatically. This would save me time and effort.

Below are a few comments after trying out the prototype implementation.

Tall style readability

I often have a series of )))) end parentheses (or brackets or braces) in my code like so:

@override
Widget build(BuildContext context) {
  return const MaterialApp(
    home: Scaffold(
        body: Padding(
            padding: EdgeInsets.all(8.0),
            child: Center(
                child: Column(children: [
              Text('Hello'),
              Text('Dart'),
              Text('World')
            ])))),
  );
}

I usually add in trailing commas like this:

@override
Widget build(BuildContext context) {
  return const MaterialApp(
    debugShowCheckedModeBanner: false,
    home: Scaffold(
      body: Padding(
        padding: EdgeInsets.all(8.0),
        child: Center(
          child: Column(
            children: [
              Text('Hello'),
              Text('Dart'),
              Text('World'),
            ],
          ),
        ),
      ),
    ),
  );
}

However, I noticed the proposed formatter takes my carefully crafted formatting and does the following with it:

@override
Widget build(BuildContext context) {
  return const MaterialApp(
    debugShowCheckedModeBanner: false,
    home: Scaffold(
      body: Padding(
        padding: EdgeInsets.all(8.0),
        child: Center(
          child:
              Column(children: [Text('Hello'), Text('Dart'), Text('World')]),
        ),
      ),
    ),
  );
}

That's not terrible, but putting all of the Column elements on one line just because they fit isn't the most readable way of displaying them. It's possible to use a comment hack (see the next section) to force tall style, but I don't know if that's what you intend to become common practice.

Forcing tall style

When I make enums, sometimes I like the tall style even if they would fit on one line:

enum Colors {
  red,
  green,
  blue,
}

The proposed formatter wouldn't allow that anymore and would reformat the code above to the following:

enum Colors { red, green, blue }

That's no problem with me. I can get used to that.

And if I really want to keep the tall style, I can add a comment after the last item like so:

enum Colors {
  red,
  green,
  blue, //
}

Now the proposed formatter leaves my code style alone.

The following is a bug, I think, but if I add a comment after the second item like so:

enum Colors {
  red,
  green, //
  blue,
}

The proposed formatter breaks the code (and its promise not change more than the style):

enum Colors { red, green, // blue }

[munificent]

Thank you for the feedback!

Re:

          child:
              Column(children: [Text('Hello'), Text('Dart'), Text('World')]),

Yeah, that looks like a bug in the prototype. I wouldn't expect it to split after a named parameter like this. It should produce output closer to what you have with the current formatter and explicit trailing commas.

The proposed formatter breaks the code (and its promise not change more than the style):

enum Colors { red, green, // blue }

That's definitely a bug. The prototype is, uh, pretty prototype-y. :)

[rakudrama]

I find the proposed style quite a bit less consistent.

This example comes from https://github.com/dart-lang/sdk/blob/main/pkg/js_ast/lib/src/nodes.dart

Old - there are basically two formats for the visitor methods, one-line and two-line.
The two-line version keeps the expression intact, and it is easy to see these methods all do the same thing.
(If I was hand-formatting I might make the middle one break after => just like the others.)

  T visitVariableDeclarationList(VariableDeclarationList node) =>
      visitExpression(node);

  T visitAssignment(Assignment node) => visitExpression(node);

  T visitVariableInitialization(VariableInitialization node) =>
      visitExpression(node);

New - there are now three formats, depending on where the line splits are.

  T visitVariableDeclarationList(
    VariableDeclarationList node,
  ) => visitExpression(node);

  T visitAssignment(Assignment node) => visitExpression(node);

  T visitVariableInitialization(VariableInitialization node) => visitExpression(
    node,
  );

The formatting does not help me see these methods all do the same thing.

The line-breaks here fight against a cognitive principle. Programs, like sentences, have structure. The big things are composed of little things, and it is helpful to ingest the small concepts completely. Line breaks in the middle of small things hinder that. Breaks higher up the semantic structure are less disruptive:

The nervous chicken
quickly crosses
the dangerous road.

is clearer than

The nervous
chicken quickly
crosses the dangerous road.

The proposed formatting is too much like the latter.

Here is an example from the same package where the main point gets lost

  Instantiator visitLiteralExpression(LiteralExpression node) =>
      TODO('visitLiteralExpression');

⟶

  Instantiator visitLiteralStatement(LiteralStatement node) => TODO(
    'visitLiteralStatement',
  );

I believe there is a middle ground that is a little bit of the old style for smaller statements, expressions and definitions, and a little bit of the proposed style for larger constructs.

[bsutton]

Generally in agreement.

I do generally prefer my commas a the start of the line as it's easier to see that it's a continuation but I suspect I'm in the minority.

           callSomething(a
               , b
               , c);

[BirjuVachhani]

I agree. Manually adding trailing commas has been such a pain! Having to not type them manually for better formatting would be great!

[Levi-Lesches]

Love it! The formatter using "short style" is the main reason why I actually don't use it, and tell my team to disable it when working on Flutter projects. Tall style is much more my style and I'd be way more likely to use the formatter consistently if it switched to that.

Regarding

  T visitVariableInitialization(VariableInitialization node) =>
      visitExpression(node);

vs

  T visitVariableInitialization(VariableInitialization node) => visitExpression(
    node,
  );

I would personally aim for the first version for shorter constructs, but in general, the second version does scale better for longer expressions. So I'd understand if the formatter picked the "wrong" one because humans disagree on this too.

[filiph]

I really like the proposal!

One nit I have is this:

// Before:
var something =
    function(argument);

// After:
var something = function(
  argument,
);

I like Before better. To me, in this particular case, it's more readable, because we're keeping the verb(noun) together as long as possible, and the var something = line is very readable/skimmable to me (it's clear that it continues).

I feel quite strongly about this when it comes to functions. I'm not so sure when it comes to constructors (Widget(...)) but my preference still holds.

I agree with @Levi-Lesches's comment above (#1253 (comment)).

[bshlomo]

A good idea but to know if the implementation is indeed good will take time
less coding is always better.
We will check and use it.
10x

[mateusfccp]

There are a few cases where I don't use trailing comma.

1. Single arguments, when the argument is a single token:

// Single token single argument
foo(10); // <--- No trailing comma

// Multi token single argument
foo(
  numberFromText('ten'),
);

2. When arguments are many but short (usually number literals)

foo(1, 2, 3); // <--- No trailing comma

// Instead of
foo( // <--- Unnecessarily long
  1,
  2,
  3,
)

Other than that, I always use trailing comma.

Overall, I think this is a good change. I think I would only avoid the case (1), as it's really unnecessary, but it would obviously make things more complicated.

[modulovalue]

My observation is that adding optional trailing commas almost always improves code readability, because it forces the formatter to put everything on a separate line, which implicitly enforces a "one concept per line"-rule, and I have found that to be very helpful when reading code.

The main change is that you no longer need to manually add or remove trailing commas

I think that automatically adding optional trailing commas could be helpful and I wouldn't be against that, but I think I wouldn't want the formatter to remove anything from my code except empty newlines. I want things to be on separate lines more often than not, and an explicit optional trailing comma has worked well as a way to tell the formatter that that's what I want.

---

If this moves forward, I think it would be great if this could be part of a bigger effort to promote more optional trailing commas as the preferred style (in, e.g., the form of recommended guidelines) + new syntax to support optional trailing commas in more places (e.g. dart-lang/language#2430)

[lesnitsky]

Could this also account for pattern-matching formatting?

Current

final child = switch (a) {
  B() => BWrapper(
      child: const Text('Hello B'),
    ), // two spaces that feel redundant
  C() => CWrapper(
      child: const Text('Hello C'),
    ),  // two spaces that feel redundant
};

Desired

final child = switch (a) {
  B() => BWrapper(
    child: const Text('Hello B'),
  ),
  C() => CWrapper(
    child: const Text('Hello C'),
  ),
};

---

UPD: I've used dart pub global run dart_style:format and it doesn't add trailing comma:

final child = switch (a) {
  B() =>
    BWrapper(child: const Text('Hello B'), prop: 'Some long text goes here'),
  C() =>
    CWrapper(child: const Text('Hello C'), prop: 'Some long text goes here'),
};

[munificent]

Could this also account for pattern-matching formatting?

Yeah, there's probably some tweaks needed there to harmonize with the proposal. Thanks for bringing that example up. :)

[lucavenir]

var something =
   function(argument);

This hurts my eyes so bad 😆 Getting rid of this would lift a lot of OCD pain when writing code

[greglittlefield-wf]

Thanks for getting this prototype together and soliciting feedback!

After trying it on some of our code, the main piece of feedback that wasn't already mentioned already is that being able to force the "tall" style with trailing commas is unfortunate.

It doesn't happen often, but when using longer line lengths where function calls don't "need" to wrap as often, you can get code that's a bit harder to read (especially when it's parentheses-heavy 😅).

For example, at line length 120:

      // Current
      (Dom.div()..addProps(getModalBodyScrollerProps()))(
        renderCalloutIcons(),
        props.calloutHeader,
        props.children,
      ),
      // Prototype
      (Dom.div()..addProps(getModalBodyScrollerProps()))(renderCalloutIcons(), props.calloutHeader, props.children),

This problem also exists for map literals, which, unlike the example above, seem to be affected more often at smaller line lengths.

• Example 1 (line length 80)

        // Current
        ..sx = {
          'width': '100%',
          'display': 'flex',
          'p': 0,
          ...?props.sx,
        }
        // Prototype
        ..sx = {'width': '100%', 'display': 'flex', 'p': 0, ...?props.sx}

• Example 2 (line length 100)

    // Current
    ..style = {
      'margin': 0,
      'padding': 0,
      'boxSizing': 'border-box',
      'display': 'block',
    }
    // Prototype
    ..style = {'margin': 0, 'padding': 0, 'boxSizing': 'border-box', 'display': 'block'}

• Example 3 (line length 120)

      // Current
      matchState.addAll(<dynamic, dynamic>{
        if (offset != null) 'offset': offset,
        if (length != null) 'length': length,
      });
      // Prototype
      matchState.addAll(<dynamic, dynamic>{if (offset != null) 'offset': offset, if (length != null) 'length': length});

We'd probably end up decreasing our line lengths to get better wrapping, which isn't ideal for some of our packages with longer class and variable names. I realize, though, that 120 is quite a bit larger that dart_style's preferred line length of 80, so I'd understand if we'd have to move closer to that to get good formatting.

But for map literals, perhaps the rules could be tweaked to prefer "tall" style more often? For example, force “tall” style if a map has more than 2 or 3 elements, or if it contains more than 1 if or for element.

[nex3]

I prefer the old version generally, but I'm willing to accept that I'm in the minority on that one and global consistency is more important than my preferences.

I'll echo that I don't like the splitting behavior for formerly-2-line => functions. It also seems very strange that, for example,

ModifiableCssSupportsRule copyWithoutChildren() =>
    ModifiableCssSupportsRule(condition, span);

becomes

ModifiableCssSupportsRule copyWithoutChildren() => ModifiableCssSupportsRule(
  condition,
  span,
);

which is actually taller than

ModifiableCssSupportsRule copyWithoutChildren() {
  return ModifiableCssSupportsRule(condition, span);
}

...which goes against the grain of => notionally being the "shorthand" method syntax.

[mernen]

Nice! Overall, I'm in favor, though I'm not sure which heuristics would work well for all cases, particularly involving collections. For example, in a layout container, I'd never want it to smash all children into a single line:

return Center(
  child: Column(
    children: [Text('Loading... please wait'), CircularProgressIndicator()],
  ),
);

---

Also, since this extra indentation of 2 levels goes completely against the grain, I'm guessing it wasn't intentional?

 placeholder: (context, url) => Center(
-  child: CircularProgressIndicator(
-    backgroundColor: Colors.white,
-  ),
-),
+      child: CircularProgressIndicator(
+        backgroundColor: Colors.white,
+      ),
+    ),

[satvikpendem]

I think enums should always be in the tall style just because reading each enumeration one line at a time makes it much easier to grasp what it's doing. I'd even support the tall style for enums that have just one member.

For functions, perhaps we should switch short vs tall based on the number of arguments, where one or two is short but 3 or more becomes tall (which is usually what I already do manually by adding commas), as well as basing it on column widths. We can even combine short and tall, perhaps:

ModifiableCssSupportsRule copyWithoutChildren() =>
  ModifiableCssSupportsRule(
    condition,
    span,
    anotherArgument,
  );

This is because I generally don't want to scroll all the way right just to see what is being returned in the arrow syntax. It is in the same vein as:

return Center(
  child: Column(
    children: ...
  ),
);

// instead of
return Center(child:
  Column(children: 
    ...
  ),
);

That is to say, the first (and current) example keeps things as left aligned as possible which makes scanning files much easier. Tthe combination of both short and tall as above feels to me to be a good compromise and is even more readable left to right, top to bottom, than either short or tall alone.

With regards to column widths, the formatter should check that first, then the number of arguments in a function or elements in an array or map, ie even if the following only has two elements, it should still force the tall version:

return Center(
  child: Column(
    children: [
      Text('Loading... please wait'),
      CircularProgressIndicator(),
    ],
  ),
);

Beyond that, I like the proposal as it saves a lot of time manually adding commas. I generally prefer the tall style for consistency.

[shovelmn12]

Why not adding a formater config so users can choose their style....

dartformat.yaml

[julemand101]

Why not adding a formater config so users can choose their style....

dartformat.yaml

https://github.com/dart-lang/dart_style/wiki/FAQ#why-cant-i-configure-it

[munificent]

Also, since this extra indentation of 2 levels goes completely against the grain, I'm guessing it wasn't intentional?

 placeholder: (context, url) => Center(
-  child: CircularProgressIndicator(
-    backgroundColor: Colors.white,
-  ),
-),
+      child: CircularProgressIndicator(
+        backgroundColor: Colors.white,
+      ),
+    ),

This one's a bug in the prototype. If a named argument's value is a closure, then it shouldn't add an extra +4 indentation like that. I'll fix that in the real implementation.

[DanTup]

Gets my 👍! I tend to use trailing commas a lot (even when not controlling the formatter, I like to not have extra modified lines in my diff if I'm appending new arguments to a "tall" list!).

I do have some questions though:

1. Do I understand correctly that the formatter will actually add/remove commas (and not just format as if they were there)?
   I ask because in the analysis_server there's some code to compute a minimal set of edits from the formatter output (because replacing the entire file will mess up breakpoints/recent navigation/etc.) and the current implementation is very simple because it takes advantage of there only being whitespace changes. It would need some tweaks (or to become a real diff) if there could be non-whitespace changes.

2. Will this functionality be opt-in (either permanently, or temporarily)?
   Many users have format-on-save enabled in VS Code and it could be surprising if in some future update (if you don't keep up with release notes etc.) you save a file you'd been working on and the formatting all changes (this exists a little today when there are minor formatting changes, but those tend to have less impact on the resulting diff). Hopefully you'd notice and could undo this before the undo buffer is lost and then migrate, but it's not guaranteed.
   Perhaps it'd be nice if the IDE could help with this - notifying that the formatting has changed and might produce significant edits and encouraging committing and reformatting the project/repo in one go?

[munificent]

1. Do I understand correctly that the formatter will actually add/remove commas (and not just format as if they were there)?

Yes.

Will this functionality be opt-in (either permanently, or temporarily)?

There won't be any permanent opt-in or opt-out because we don't have the resources to maintain two formatting styles in perpetuity. There will be an experimental period where the new style is hidden behind a flag, mostly so that I can land in-progress work on master, but I expect few users to see that.

Once it's fully working and ready to ship, there may be a temporary opt-in (or out, not sure about the default) in order to ease the migration for users. I'm waiting for feedback to come in to get a sense of how important it is. So far, based on survey results, it doesn't seem to be a high priority for most users.

I'll try to get a better feel for what will help the community when a real implementation is farther along. I definitely want to minimize pain.

[satvikpendem]

I don't think it's necessarily high priority in terms of timeline (as I believe many will wait and adopt it when they wish to migrate) but it confers quite a large benefit to mental overhead as other languages don't really have this notion of changing commas to fix formatting, I've really only seen that in Dart. Most languages have their own fixed formatter, ie prettier, black, rustfmt, etc where most people don't really think about the formatting manually, but in Dart it seems we need to.

[saierd]

The last part means that users can no longer hand-author a trailing comma to mean, "I know it fits on one line but force it to split anyway because I want it to."

I think it is quite important to have this ability for Flutter code. Take for example this snippet:

Row(children: [
  Left(),
  Right(),
]);

This is not just a bunch of functions. It's a widget tree and formatting it in tall style reflects that. For this reason the Flutter documentation explicitly recommends to always add trailing commas in widgets to take advantage of this formatting behavior.

For users who prefer a tall style, they must be careful to add a trailing comma and then reformat whenever an existing argument or parameter list that used to fit on one line no longer does and gets split. By default, as soon as the list overflows, it will get the short style.

I find that enforcing trailing commas in places where wrapping happened anyway is not a problem in practice, since the require_trailing_commas rule exists and can automatically fix this.

[hpoul]

I always thought controlling the formatter by just appending a , felt really natural.. sometimes i want short lines to break and use tall formatting, either to stay consistent with other lines which happen to be a few characters longer, or to minimize diffs when more items are added to a list or enum, etc..

The workaround to use a // comment (#1253 (comment)) to force wrapping would definitely not be an improvement 🙈

[munificent]

But for map literals, perhaps the rules could be tweaked to prefer "tall" style more often? For example, force “tall” style if a map has more than 2 or 3 elements, or if it contains more than 1 if or for element.

Yeah, that's not a bad idea. I'm interested in exploring this too. There is something roughly in the same direction in the current formatter in that it will split an outer collection literal if it contains another collection literal, even if the outer one otherwise doesn't need to split.

I've considered other rules around splitting when not strictly necessary to fit the line length, but I haven't really tried to implement anything because it's not clear what those rules should be and how they should best adapt to different line lengths.

One thing I've talked with @Hixie about is having the line length restriction work more like Prettier:

In code styleguides, maximum line length rules are often set to 100 or 120. However, when humans write code, they don’t strive to reach the maximum number of columns on every line. Developers often use whitespace to break up long lines for readability. In practice, the average line length often ends up well below the maximum.

Prettier’s printWidth option does not work the same way. It is not the hard upper allowed line length limit. It is a way to say to Prettier roughly how long you’d like lines to be. Prettier will make both shorter and longer lines, but generally strive to meet the specified printWidth.

So instead of treating it like a hard limit (which it currently does), it would be a softer boundary where lines are somewhat punished for going over when calculating the cost, but not heavily. I'm interested in exploring this approach, but I'm not planning to do that for this proposed set of changes. There are enough changes already queued up with this as it is. :)

[alestiago]

Thanks @munificent for this proposal. Overall, I'm quite happy with the change. I was wondering how would this affect (or if it has been considered) matrix representation, since currently it is not very convenient to read matrices.

I would like:

  Matrix4 m =
      Matrix4(11, 12, 13, 14, 21, 22, 23, 24, 31, 32, 33, 34, 41, 42, 43, 44);

To be something as:

  Matrix4 m = Matrix4(
      11, 12, 13, 14,
      21, 22, 23, 24,
      31, 32, 33, 34,
      41, 42, 43, 44);

Definitely not something as:

  Matrix4 m = Matrix4(
    11,
    12,
    13,
    14,
    21,
    22,
    23,
    24,
    31,
    32,
    33,
    34,
    41,
    42,
    43,
    44,
  );

The overall idea is simply to read the matrix as it is usually written in mathematics.

This comment is somewhat related to what was mentioned here.

[julemand101]

@alestiago
I think it is going to be hard to know for sure how people wants to split their lists/arguments for best formatting. The current practice is to add comments to force the line breaks:

  Matrix4 m = Matrix4(
    11, 12, 13, 14, //
    21, 22, 23, 24, //
    31, 32, 33, 34, //
    41, 42, 43, 44, //
  );

I hope this is still going to be a valid solution after the suggested change in this proposal.

[alestiago]

@julemand101 , thanks for hopping in! I also use the comments to avoid the new line, and also hope that this behaviour is improved or kept the same after the proposed changed.

[liranzairi]

I wish I saw this thread before and had a chance to vote too. I understand all the reasoning behind the new format, but there are also benefits to the old style:

void foo(
  String firstName,
  String lastName,
  String userName,
) {
  ...
}

• For many developers its much more readable this way
• It's easier to add/remove parameters

At the end of the day different developers have their different preferences. Is there any chance you'll allow us to choose between the two format versions?

[Merrit]

The discussion on this has been moved to 2 new issues: #1660 #1652

It would be best to comment and vote on those issues, rather than on this old issue that isn't being tracked anymore.

[bambinoua]

@mit-mit

The formatter style is not gated on what version of the Dart SDK you are using. You can use new Dart SDKs like Dart 3.7, and still get the old style.

Could you please to explain how can I use 3.7 version of dart with old style of formatting?

[julemand101]

@bambinoua
Go into your pubspec.yaml and set your lowest compatible version to less than 3.7.0. So e.g.:

environment:
  sdk: "^3.6.0"

This will still allow you to use Dart 3.7 and upwards. But will not enable features introduced in Dart 3.7 and upwards.

In general, Dart SDK knows when features are introduced and can disable them in projects based on pubspec.yaml. So with Dart 3.7, you can still go as low as Dart 2.12 (where null-safety got introduced) in your pubspec.yaml.

[bambinoua]

@julemand101

In the comment which I quoted there were words You can use new Dart SDKs like Dart 3.7 And under words use 3.7 version I meant using version 3.7 with all features which 3.7 suggests.

It looks like the comment from @mit-mit was a little misleading. So using of version 3.7 (of course with all ite features) is impossible w/o new formatter. It is pitty.

[julemand101]

It looks like the comment from @mit-mit was a little misleading. So using of version 3.7 (of course with all ite features) is impossible w/o new formatter. It is pitty.

There are not that many features introduced with Dart 3.7 which have an impact on your choice of version in pubspec.yaml:
https://github.com/dart-lang/sdk/blob/stable/CHANGELOG.md#370

The only one I can see you would likely care about is the wildcard variables. While they are nice, they are also not really required in most cases.

I think the suggested workaround is "good enough" right now. Not saying this is good if Dart 3.8 introduces some exciting changes but we should also expect Dart 3.8 come with an improved Dart style that have taken care of the most serious issues people have reported about the new formatting style.

The issue around just allowing the old formatting to work on newer Dart versions is that this does not really work in practice if later versions of Dart introduces syntax changes, since we then need to write those into the old formatter code. And therefore keep two formatting code bases updated. Yes, for Dart 3.7, it is likely not that much of an issue. But later on, it becomes a problem.

[jchirinosodio]

I hate it now removing commas :/

[MiniSuperDev]

Does anyone know if there is an estimated time for a next version of this style?
Or what solution the team is taking into account to implement for the next release? maybe #1660 #1652 ?

Or maybe add support for opting out the new formatter and use the previous, while they refine it further due to all the negative feedback they've encountered?

And I understand that the team is reviewing this, but as you can see many have chosen to stay on flutter 3.27.
What this means is that they are forced to not use the new features of 3.29 or dart 3.7, and in the next versions they would not update either.

I've started a few new projects and have chosen not to use flutter 3.29 until #1660 or a similar feature is implemented because the code is very ugly to read and I know that when this or a similar feature is implemented I would have to refactor the style of the entire project, which would create a lot of unnecessary diffs.

Thanks

[julemand101]

And I understand that the team is reviewing this, but as you can see many have chosen to stay on flutter 3.27.

@MiniSuperDev What prevents you from using latest version of Flutter, but with the following in your pubspec.yaml?

environment:
  sdk: "^3.6.0"

This should allow you to use latest features from the Flutter 3.29. Yes, you can't use the few Dart features introduced with Dart 3.7, but this will mostly be the wildcard variables. Which I think you can do without since that is less important than the Flutter features.

But Dart 3.7 will use the old formatting code if it detects the lower bound for Dart version to be lower than 3.7. So this workaround should be "good enough" for most people for now. Yes, this is much less acceptable for e.g. Dart 3.8 (and later) since we are stuck with features from Dart by doing this. But, it does allow us to wait, for now, for Dart Style improvements.

[HyperJames]

This discussion was closed and two new issues have been raised: #1660 and #1652

I'd recommend anyone who wants to see a change on the Dart formatter and styling now shows their support and thoughts on those two tickets.

[munificent]

Does anyone know if there is an estimated time for a next version of this style?

No time frame, but I'm working on it as fast as I can.

Or what solution the team is taking into account to implement for the next release? maybe #1660 #1652 ?

I am hoping for #1660, but that depends on coming up with a heuristic for argument splitting that seems to do a good enough job to please most users. That's fairly tricky.

If that doesn't work out, then #1652 is on the table, but I have a lot of feedback from teammates and users not on this issue tracker that they really don't want the formatter to do #1652. Fully automating trailing commas was one of the reasons that the Flutter team was finally willing to adopt the new formatter.

Or maybe add support for opting out the new formatter and use the previous, while they refine it further due to all the negative feedback they've encountered?

You can use the latest Flutter while opting out of the new style by setting an SDK constraint like @julemand101 says.

[azimuthdeveloper]

Does anyone know if there is an estimated time for a next version of this style?

No time frame, but I'm working on it as fast as I can.

Or what solution the team is taking into account to implement for the next release? maybe #1660 #1652 ?

I am hoping for #1660, but that depends on coming up with a heuristic for argument splitting that seems to do a good enough job to please most users. That's fairly tricky.

If that doesn't work out, then #1652 is on the table, but I have a lot of feedback from teammates and users not on this issue tracker that they really don't want the formatter to do #1652. Fully automating trailing commas was one of the reasons that the Flutter team was finally willing to adopt the new formatter.

Surely if #1652 was user-configurable, opt-in by default, their codebase would be unaffected? And they could continue unaffected? And all of us trailing-comma weirdos could just opt-out as required.

I think the application of Dart, and Dart within Flutter, is too broad to come up with a heuristic that would solve all/nearly all cases. The fact its used for business logic and UI means that different dart files, while programatically similar, could require different rules. My only contribution to this is wanting to wrap children of Rows and Columns without using triple slashes.

Can I ask - what are your priorities here? Because we can only see the things that occur on GItHub, we can't see what your teammates and people who aren't on this issue are saying. It seems unanimous on this tracker, so it would be good to understand from a broader perspective what the overall feel is and where you think this will go. More specifically, what are you working on? Trailing comma implementation or heuristics? Both? Neither?

[jamesderlin]

If that doesn't work out, then #1652 is on the table, but I have a lot of feedback from teammates and users not on this issue tracker that they really don't want the formatter to do #1652. Fully automating trailing commas was one of the reasons that the Flutter team was finally willing to adopt the new formatter.

Are they specifically against having a project-wide option to enable or disable removing trailing commas? If it's an option, they can still get the full automation they want.

This seems to me like the sort of thing that's sufficiently contentious (like the line-length default) that maybe an option is warranted. And an option would buy time to maybe figure out better heuristics later.

[munificent]

Surely if #1652 was user-configurable, opt-in by default, their codebase would be unaffected? And they could continue unaffected? And all of us trailing-comma weirdos could just opt-out as required.

Yes, but:

• We need to implement, test, and maintain both the configuration being on and off (along with all combinations of any other future configuration options).
• That option needs to be plumbed through every possible tool and code generator that runs the formatter. Otherwise you'll get diff churn when one tool sees that option and formats a file and then another tool that doesn't see the option formats the same file a different way. We're already running into problems like that with configurable page width and code generators.
• People now have to spend time arguing about whether their team should enable or disable that option.

I think the application of Dart, and Dart within Flutter, is too broad to come up with a heuristic that would solve all/nearly all cases. The fact its used for business logic and UI means that different dart files, while programatically similar, could require different rules. My only contribution to this is wanting to wrap children of Rows and Columns without using triple slashes.

It's not clear to me that this is actually true. The premise behind eagerly splitting argument lists that would otherwise fit is because they are easier to read that way. Why would that only be true for Flutter UI code and not any other kind of Dart code? Why is this so hard to read that users would rather downgrade Flutter than deal with it:

Center(child: Text('Hi there'))

But then this is apparently fine:

Business(logic: Data('Other stuff'))

I understand that, yes, it's because Flutter UI code is more or less a markup tree and it's useful to see the tree structure more clearly. But it's not clear to me that isn't equally true of any deeply nested function call tree. Once you're a couple of function calls deep, using indentation to visually keep track of nesting is probably going to be easier than counting brackets on a single line, regardless of what that code is for.

Can I ask - what are your priorities here? Because we can only see the things that occur on GItHub, we can't see what your teammates and people who aren't on this issue are saying. It seems unanimous on this tracker, so it would be good to understand from a broader perspective what the overall feel is and where you think this will go. More specifically, what are you working on? Trailing comma implementation or heuristics? Both? Neither?

Currently, I'm trying to find a good set of heuristics that automatically produces the output that users seem to want based on the code they have put in the related issues along with a large corpus of open source code.

Simply preserving trailing commas is relatively easy to implement. It's just that it's an anti-feature for a significant set of users (who mostly aren't showing up on the issue tracker here). And it breaks an invariant that has been in the formatter and valuable for many years which I would strongly prefer to maintain if at all possible.

[nex3]

It may also be worth noting that even in literal markup languages it's fairly common to have tree nodes laid out all on one line even even if they contain children. To pick an arbitrary example (the repo that happened to be highest on GitHub's trending HTML repos as I wrote this):

https://github.com/cotes2020/jekyll-theme-chirpy/blob/e3158642c3aa248fc1f655773e903cafa862972e/_layouts/archives.html#L30

This is morally equivalent to the Flutter-style:

Link(url: relativeUrl(post.url), child: Text(post.title))

My point is that to some degree a lot of what we perceive as "readability" comes down to what we're used to, and even in a markup context putting short, shallow trees on a single line can be considered perfectly readable and idiomatic. Bob will do his very best to make the formatter's output match what a human would write as much as possible, but I think it's also worthwhile for us to make an effort to try to meet that halfway and make an earnest effort to get used to the output it produces instead of expecting it to be exactly what we would have written by hand. I personally don't really like tall style at all! But I'm really making an effort to get used to it because I think the benefits of having an opinionated formatter that sets the standard for the language are worth it.

And those benefits are substantial. Having the formatter automatically handle trailing commas means that every list that has to split and every argument list that gets a character too long automatically gets written in the correct way without any human intervention. And it means that Dart code is far more portable and easier to read across teams and projects than it would have been otherwise. Most languages don't get that. Even among languages that do get that, it's usually because their standard formatters make massive compromises on usability (like gofmt not handling line splitting at all). Surely having the formatter create a few line breaks differently than you would have—and probably fewer once the new heuristic gets released!—is worth that.

[hpoul]

but I have a lot of feedback from teammates and users not on this issue tracker

Funny that the original argument for the new formatter was the overwhelmed 👍 votes on the "tall style" issue. But now the 162 👍 vs 14 👎 on #1652 don't matter. Maybe it is time to include this question about automatic comma removal in a broader flutter survey. Hopefully with a less misleading title. People like the tall style, but don't like being forced into single line style. (At least I do 🙈)

[munificent]

Funny that the original argument for the new formatter was the overwhelmed 👍 votes on the "tall style" issue.

What's funny about that?

But now the 162 👍 vs 14 👎 on #1652 don't matter.

Those certainly matter, which is why I am working full time on figuring out a better approach to trailing commas. Note that the number of 👍 on this proposal is still much higher than the number of 👍 requesting to preserve trailing commas.

Maybe it is time to include this question about automatic comma removal in a broader flutter survey. Hopefully with a less misleading title. People like the tall style, but don't like being forced into single line style. (At least I do 🙈)

Including this in the next Flutter survey is a good idea. I'm not sure if it will work out timing-wise, but I'll look into it.

[azimuthdeveloper]

Funny that the original argument for the new formatter was the overwhelmed 👍 votes on the "tall style" issue.

What's funny about that?

But now the 162 👍 vs 14 👎 on #1652 don't matter.

Those certainly matter, which is why I am working full time on figuring out a better approach to trailing commas. Note that the number of 👍 on this proposal is still much higher than the number of 👍 requesting to preserve trailing commas.

That's because that issue was opened in 2023 for reactions, and the other issue was opened 2 weeks ago for reactions.

[timnew]

I guess most people didn't even noticed it until being hit on the face...

That's because that issue was opened in 2023 for reactions, and the other issue was opened 2 weeks ago for reactions.

[alanfortlink]

Regarding #1652 , this is exactly the kind of thing that is configurable in pretty much every formatter. Yes, you will have to maintain that, but so does every formatter. This isn't a novel idea, this isn't something revolutionary, this is basically industry-standard at this point.

@munificent, I see you're still saying "[Regarding #1660]... If that doesn't work out, then #1652 is on the table". It seems that you still think heuristics will be enough, and I hope they are for yours/flutter's use case, but they shouldn't override the developer, or the developer should be able to turn that off... it just doesn't make any sense.

There are already so many examples, and for each heuristic, people will find a different example for which the heuristic doesn't work... So... What kind of argument do you need to change your mind? I'd love to try and put something together to help the discussion.

[matheusoreis]

As an old Dart and Flutter developer, since the beginning we have always used commas to break the code that we find ugly! Removing this functionality of commas is a shot in the foot! When the code gets big or even widgets that contain many children it becomes horrible to visualize the code! I believe that the new style is valid as long as it does not interfere directly with the , at the end of each line! This is something that has always been there in Flutter and removing it from one moment to the next without giving the possibility of putting the , for forced formatting is HORRIBLE!

[AlexDochioiu]

As an old Dart and Flutter developer, since the beginning we have always used commas to break the code that we find ugly! Removing this functionality of commas is a shot in the foot! When the code gets big or even widgets that contain many children it becomes horrible to visualize the code! I believe that the new style is valid as long as it does not interfere directly with the , at the end of each line! This is something that has always been there in Flutter and removing it from one moment to the next without giving the possibility of putting the , for forced formatting is HORRIBLE!

+1 to this. Now I have to add an empty comments in many places after comma to block the auto-format making everything unreadable.

[mateusfccp]

I didn't test the new formatter until this week. I confess I was afraid of using it because of how people were reacting, but I must say I am positively impressed. It takes a while to get used to the automatic comma inserting/removing, but it is easier than having to do yourself.

There are some adjustments that may improve it, and I think #1660 will put it into a state where most people will be satisfied, even if it is not exactly how they would format a specific piece of code.

[BuyMyBeard]

As an old Dart and Flutter developer, since the beginning we have always used commas to break the code that we find ugly! Removing this functionality of commas is a shot in the foot! When the code gets big or even widgets that contain many children it becomes horrible to visualize the code! I believe that the new style is valid as long as it does not interfere directly with the , at the end of each line! This is something that has always been there in Flutter and removing it from one moment to the next without giving the possibility of putting the , for forced formatting is HORRIBLE!

I have to disagree. I have a few interns on my team, and as a code owner, having the code uniformized for everyone is a massive time saver. Most developers do not have attention to detail, especially junior devs, and I'd have to either DGAF about the uniformity of the formatting, or nitpick in every code review and get on their nerves.

Having a formatter be sensitive to formatting goes against the principle of formatting. I think the reason it ruffles some feathers is because an existing feature was removed, but I don't think it should have been a feature in the first place.

The only thing I'd like to concede is that I'd like if the built-in formatter was a bit more configurable. They recently added the page width config, but to the extent of my knowledge, this is the first time they implemented one.

[intonarumori]

This was a horrible surprise, breaking my workflow, generating lots of unwanted code changes in Git.
Please, give us back the ability to use trailing commas as a way to control our own code.

[jamesderlin]

Guys, you're beating a dead horse. Bob already agreed to add an option to preserve trailing commas and already made a change to do it.

We don't need more "me too" comments, which will make this thread harder to read and harder to find the issues that are actually tracking future work:

• Preserve trailing commas #1652
• Split argument lists that would otherwise fit #1660

If you have specific examples that you think would be useful for future heuristics, you should add them to the other issues.

[munificent]

OK, I'm going to go ahead and lock this issue. Using a single (closed) issue to track all complaints about the new formatter is obviously not sustainable or effective. If you have problems with the new formatter, please comment on existing issues that describe that specific problem or file new issues.

If you are unhappy about the new formatter not preserving commas, your complaint is heard, a fix is implemented, and it will ship as soon as possible.