munificent
commented
9 years ago I understand the desire here, but it goes against the fundamental goals of the formatter. Its goals, in order of descending priority, are:
- Produce consistently formatted code.
- End debates about style issues in code reviews.
- Free users from having to think about formatting.
- Produce beautiful, readable output that helps users understand the intent and structure of the code.
Point number 4 is critical because if the formatter isn't good enough, people simply won't use it. In some cases, though, it can't do as good a job as a human can, because a human has semantic knowledge, like "split here to keep these two arguments together since they form a logical pair".
A "let the human do this" annotation would give an escape hatch for those cases. Unfortunately, it does so at the expect of the first three goals. As soon as you have these annotations, you're right back to quibbling about how the code inside them should be formatted. Worse, you now also open the metargument about where in the code you should be allowed to use the annotations. I certainly don't want to start more style debates!
The set of places where a human could better than the formatter shrinks with every release. Note that I use "could" deliberately here. While a human can in theory do a better job hand-formatting sometimes, we're also error-prone.
Your carefully hand-formattted example has two erroneous spaces before 'cauldronBubble'. Today, the formatter fixes that error and formats your example to:
Foo barBaz() => new Quux({
'alpha.beta.gamma': [
new Zuul({
'yarrr': Abracadabra.OPEN_SESAME,
}, {
'toil': {'trouble': {'fireBurn': {'cauldronBubble': EYE_OF_NEWT,}}}
})
]
});Personally, I prefer that over your hand formatting. If we take your suggestion on #223 (which I like but I need to see how it plays out in practice), you get:
Foo barBaz() => new Quux({
'alpha.beta.gamma': [
new Zuul({
'yarrr': Abracadabra.OPEN_SESAME,
}, {
'toil': {
'trouble': {
'fireBurn': {'cauldronBubble': EYE_OF_NEWT,}
}
}
})
]
});I think that's the best formatting of all.
Finally—and this is the least important motivation—not having an escape hatch keeps me honest. Since the formatter will touch all of your code, it forces me to work very hard to get it to do so in a way you like. If you could just turn off formatting, it would be easy for me to close bugs with just, "Eh, just don't format that bit."
tlarsen4google
lyceel
EmmanuelOga
AldoMX
aktxyz
Hixie
benthillerkus
Since no formatter is perfect (e.g., some const/final nested collection constructs try to represent actual readable structure meaning in the code via their indentation that the formatter cannot be expected to understand and preserve), formatter off/on comment pairs should be recognized that turn off reformatting for the specified lines in between these delimiters.
Yes, use of this construct should be discouraged and limited. Perhaps emit a warning as dartfmt is run indicating that it encountered such blocks of unformatted code?
Also, it is only reasonable to require complete constructs be present between the delimiters, and not expect the formatter to do anything reasonable when the delimiters arbitrarily break up the middle of some block level construct. For example, the formatter could produce an error, or just not be expected to do anything sane, for misuses like:
At worst, such unformatted segments that span block boundaries should produced undefined results for the rest of the source file. At best, an error should be printed and formatting should stop.