[dart-announce] A change process for 'dartfmt' / 'dart format'
33 views
Skip to first unread message
'Bob Nystrom' via Dart Announcements
May 18, 2021, 2:29:13 PM5/18/21
to announce
TL;DR: We're moving to a slightly more formal process for changing dart format to make it easier to get user feedback on style changes.
When I first inherited Phil's dartfmt implementation and fleshed it out, I based the style rules on all the existing hand-formatted Dart code I could find. I also used Google's style guides for other similar languages (Java, JavaScript, C++) as a reference, since consistency across those makes things easier for Googlers that span languages.
As the userbase grows, it gets harder to change the formatting. Introducing formatting churn to existing formatted code has a real cost to all users. So far, I've handled that by mostly leaving the style alone. Most changes have either been around new syntax which isn't widely used yet or in rare combinations of features where a style change doesn't affect much existing code.
This is generally a good thing! The key goals of the formatter are consistency and saving user time. We lose both of those if the style is always changing in unfamiliar ways and we're all spending lots of time debating style rules and reformatting existing code.
But there is a risk that the style grows out of date as the way Dart is used evolves over time. There may be formatting changes that would significantly improve readability in the eyes of most users but we don't know because there's no process to find out. To address that, we're launching one.
This process still requires some taste and judgement from the Dart team. Good style requires thinking about how a change harmonizes with other formatting rules. Some formatting styles may be technically difficult to implement. It may be hard to synthesize a general rule from a couple of desired example outputs. Also, changes that are small enough in scope or clearly improvements may be safe to simply land.
Our aim is to allow the formatter's style to slowly evolve to fit the kind of Dart code being written today. We want it to be as readable as possible to as many as possible. We will not please everyone. Even changes that most people like may be too costly in terms of churn.
Our aim is not to re-litigate every single style rule. Our time on this planet is finite and most style changes have little real impact on readability regardless of our deep emotional attachment to them. The main thing that makes code readable is familiarity and the primary way to get familiarity is to leave well enough alone. It's good to remember that our users never see how nicely formatted our code is, and time spent on formatting is time not spent adding features for them.
The process we plan to follow is here:
https://github.com/dart-lang/dart_style/wiki/Change-process
I imagine we'll probably tweak it some as we get a feel for how it works in practice. Thanks for your patience and may your Dart experience be joyful.
Cheers!
– bob
-- When I first inherited Phil's dartfmt implementation and fleshed it out, I based the style rules on all the existing hand-formatted Dart code I could find. I also used Google's style guides for other similar languages (Java, JavaScript, C++) as a reference, since consistency across those makes things easier for Googlers that span languages.
As the userbase grows, it gets harder to change the formatting. Introducing formatting churn to existing formatted code has a real cost to all users. So far, I've handled that by mostly leaving the style alone. Most changes have either been around new syntax which isn't widely used yet or in rare combinations of features where a style change doesn't affect much existing code.
This is generally a good thing! The key goals of the formatter are consistency and saving user time. We lose both of those if the style is always changing in unfamiliar ways and we're all spending lots of time debating style rules and reformatting existing code.
But there is a risk that the style grows out of date as the way Dart is used evolves over time. There may be formatting changes that would significantly improve readability in the eyes of most users but we don't know because there's no process to find out. To address that, we're launching one.
This process still requires some taste and judgement from the Dart team. Good style requires thinking about how a change harmonizes with other formatting rules. Some formatting styles may be technically difficult to implement. It may be hard to synthesize a general rule from a couple of desired example outputs. Also, changes that are small enough in scope or clearly improvements may be safe to simply land.
Our aim is to allow the formatter's style to slowly evolve to fit the kind of Dart code being written today. We want it to be as readable as possible to as many as possible. We will not please everyone. Even changes that most people like may be too costly in terms of churn.
Our aim is not to re-litigate every single style rule. Our time on this planet is finite and most style changes have little real impact on readability regardless of our deep emotional attachment to them. The main thing that makes code readable is familiarity and the primary way to get familiarity is to leave well enough alone. It's good to remember that our users never see how nicely formatted our code is, and time spent on formatting is time not spent adding features for them.
The process we plan to follow is here:
https://github.com/dart-lang/dart_style/wiki/Change-process
I imagine we'll probably tweak it some as we get a feel for how it works in practice. Thanks for your patience and may your Dart experience be joyful.
Cheers!
– bob
For more ways to connect visit https://dart.dev/community
Reply all
Reply to author
Forward
0 new messages