tag | e407f30d717078d5db2ea9d004afcc77cdda5f24 | |
---|---|---|
tagger | Bob Nystrom <rnystrom@google.com> | Fri Jun 19 13:16:17 2015 -0700 |
object | 23b5b8ac611c14bae2006fa78cfc71f3c696f244 |
0.2.0-rc.1
commit | 23b5b8ac611c14bae2006fa78cfc71f3c696f244 | [log] [tgz] |
---|---|---|
author | Bob Nystrom <rnystrom@google.com> | Fri Jun 19 13:14:45 2015 -0700 |
committer | Bob Nystrom <rnystrom@google.com> | Fri Jun 19 13:14:45 2015 -0700 |
tree | b5353d14b4089c90f7f5db382faa0e578f14b951 | |
parent | b3cc8107bf212965023452dabfb12b922176abc2 [diff] |
Release dart_style 0.2.0-rc.1. R=kevmoo@google.com, pquitslund@google.com Review URL: https://chromiumcodereview.appspot.com//1193863004.
The dart_style package defines an automatic, opinionated formatter for Dart code. It replaces the whitespace in your program with what it deems to be the best formatting for it. Resulting code should following the Dart style guide but, moreso, should look nice to most human readers, most of the time.
It handles indentation, inline whitespace and (by far the most difficult), intelligent line wrapping. It has no problems with nested collections, function expressions, long argument lists, or otherwise tricky code.
The package exposes a simple command-line wrapper around the core formatting library. The easiest way to invoke it is to globally activate the package and let pub put its executable on your path:
$ pub global activate dart_style $ dartfmt ...
If you don't want dartformat
on your path, you can run it explicitly:
$ pub global activate dart_style --no-executables $ pub global run dart_style:format ...
The formatter takes a list of paths, which can point to directories or files. If the path is a directory, it processes every .dart
file in that directory or any of its subdirectories.
By default, it formats each file and just prints the resulting code to stdout. If you pass -w
, it will instead overwrite your existing files with the formatted results.
You may pass a --line-length
option to control the width of the page that it wraps lines to fit within, but you're strongly encouraged to keep the default line length of 80 columns.
If you want to use the formatter in something like a presubmit script or commit hook, you can use the --dry-run
option. If you pass that, the formatter prints the paths of the files whose contents would change if the formatter were run normally. If it prints no output, then everything is already correctly formatted.
The package also exposes a single dart_style library containing a programmatic API for formatting code. Simple usage looks like this:
import 'package:dart_style/dart_style.dart'; main() { var formatter = new DartFormatter(); try { print(formatter.format(""" library an_entire_compilation_unit; class SomeClass {} """)); print(formatter.formatStatement("aSingle(statement);")); } on FormatterException catch (ex) { print(ex); } }
The has a few goals, in order of descending priority:
Produce consistently formatted code. Consistent style improves readability because you aren‘t distracted by variance in style between different parts of a program. It makes it easier to contribute to others’ code because their style will already be familiar to you.
End debates about style issues in code reviews. This consumes an astonishingly large quantity of very valuable engineering energy. Style debates are time-consuming, upset people, and rarely change anyone's mind. They make code reviews take longer and be more acromonious.
Free users from having to think about and apply formatting. When writing code, you don‘t have to try to figure out the best way to split a line and then pain-stakingly add in the line breaks. When you do a global refactor that changes the length of some identifier, you don’t have to go back and rewrap all of the lines. When you're in the zone, you can just pump out code and let the formatter tidy it up for you as you go.
Produce beautiful, readable output that helps users understand the code. We could solve all of the above goals with a formatter that just removed all whitespace, but that wouldn't be very human-friendly. So, finally, the formatter tries very hard to produce output that is not just consistent but readable to a human. It tries to use indentation and line breaks to highlight the structure and organization of the code.
In several cases, the formatter has pointed out bugs where the existing indentation was misleading and didn‘t represent what the code actually did. For example, automated formatted would have helped make Apple’s “gotofail” security bug easier to notice:
if ((err = SSLHashSHA1.update(&hashCtx, &signedParams)) != 0) goto fail; goto fail; if ((err = SSLHashSHA1.final(&hashCtx, &hashOut)) != 0) goto fail;
The formatter would change this to:
if ((err = SSLHashSHA1.update(&hashCtx, &signedParams)) != 0) goto fail; goto fail; // <-- not clearly not under the "if". if ((err = SSLHashSHA1.final(&hashCtx, &hashOut)) != 0) goto fail;
First of all, that's not a question. But, yes, sometimes you may dislike the output of the formatter. This may be a bug or it may be a deliberate stylistic choice of the formatter that you disagree with. The simplest way to find out is to file an issue.
Now that the formatter is fairly mature, it‘s more likely that the output is deliberate. If your bug gets closed as “as designed”, try not to be too sad. Even if the formatter doesn’t follow your personal preferences, what it does do is spare you the effort of hand-formatting, and ensure your code is consistently formatted. I hope you'll appreciate the real value in both of those.
Even a really sophisticated formatter can't beat a human in all cases. Our semantic knowledge of the code can let us show more than the formatter can. One escape hatch would be to have a comment telling the formatter “leave this alone”.
This might help the fourth goal above, but does so at the expense of the first three. We want code that is consistent and we want you to stop thinking about formatting. If you can decide to turn off the formatter, now you have regions of code that are inconsistent by design.
Further, you're right back into debates about how the code in there should be formatted, with the extra bonus of now debating whether or not that annotation should be used and where. None of this is making your life better.
Yes, maybe you can hand-format some things better than the formatter. (Though, in most cases where users have asked for this, I've seen formatting errors in the examples they provided!) But does doing that really add enough value to make up for re-opening that can of worms?
You can rely on the formatter to not break your code or change its semantics. If it does do so, this is a critical bug and we'll fix it quickly.
The rules the formatter uses to determine the “best” way to split a line may change over time. We don‘t promise that code produced by the formatter today will be identical to the same code run through a later version of the formatter. We do hope that you’ll like the output of the later version more.
if
statements better?If you have a statement like:
if (someVeryLongConditional || anotherLongConditional) function(argument, argument);
It will format it like:
if (someVeryLongConditional || anotherLongConditional) function( argument, argument);
You might expect it to break before function
. But the Dart style guide explicitly forbids multi-line if
statements that do not use {}
bodies. Given that, there's never a reason for the formatter to allow splitting after the condition. This is true of other control flow statements too, of course.
The formatter has a simple, restricted charter: it rewrites only the non-semantic whitespace of your program. It makes absolutely no other changes to your code.
This helps keep the scope of the project limited. The set of “clean-ups” you may want to do is unbounded and much fuzzier to define.
It also makes it more reliable to run the formatter automatically in things like presubmit scripts where a human may not be vetting the output. If the formatter only touches whitespace, it's easier for a human to trust its output.