Please help test Rustfmt


#1

Over the next few months, we’re making a big push to release a v1.0 for Rustfmt. It would be really useful if you could help by using Rustfmt and reporting any errors you find. I’m particularly interested in crashes, and errors where correct code is broken by re-formatting. If you find problems, please report them at https://github.com/rust-lang-nursery/rustfmt/issues

Using Rustfmt is super-easy! To install: cargo install rustfmt, and to use it on your project: cargo fmt.

Rustfmt will create backups of any file it changes, so you shouldn’t lose work. But, since this is beta software, please use version control or keep your own backups too.

The 1.0 will not set the formatting styles or defaults for all time. There will be more options and improvements in the future, and a process (probably using RFCs) for setting the default styles, probably in conjunction with a detailed style guide.

The 1.0 release will offer stability guarantees about styling options and intends to be a milestone in terms of usability and stability.


#2

Are default configuration options going to be reviewed before 1.0? Is there a need to collect stats about what people use as config if they don’t use the defaults?


#3

Are default configuration options going to be reviewed before 1.0?

No. Default options will be decided post-1.0. There will be some review of the options available, but just to make sure they are coherent and well-organised, not to remove any.


#4

Are the options documented somewhere ? I can do rustfmt --config-help, but messages like this

chain_base_indent [Inherit|Tabbed|Visual] Default: Visual
Indent on chain base

are not really helpful to know what this setting does.

Some examples of the formatting would be very nice, I am thinking of something like clippy’s wiki page for lints.


#5

I think it may make sense to review defaults before 1.0.

And I think you and @Azerupi are talking about different defaults here :slight_smile:

There is default style for Rust code, which should be decided after 1.0.

There are default options of rustfmt program, which can be tweaked before 1.0 so that if user uses rustfmt for the first time without any configuration, then she gets some reasonable formatting.

That said, I do think that current defaults are good enough, but it’s always better to doublecheck.


#6

Ok, I have used rustfmt on my project and have not encountered any major problems. I had a problem one time where a PR running rustfmt on someones project was rejected because it messed up the tests and removed the alignment in match statements. Here is the relevant PR. I filed an issue for the match statements but not for the tests.

I was talking about the defaults rustfmt uses when no configuration is provided. :slight_smile:


One thing I would really like to have is the possibility to run rustfmt automatically every time I run cargo build. I tend to forget to run cargo fmt regularly. I am not sure if that would even be possible currently though, and it’s probably out of scope for 1.0


#7

Are the options documented somewhere ?

Options are not really documented beyond the help message. You can look at config.rs, most of the enums used in the options are commented to explain what the different options mean.

I’d be really happy to have better docs here if anyone is interested in writing up this info.

I think it may make sense to review defaults before 1.0.

That said, I do think that current defaults are good enough, but it’s always better to doublecheck.

We’ve been keeping an eye on the defaults and tweaking a fair bit as we go along. I hope they are in a pretty good state. There will be more fine-tuning as we run Rustfmt on more code though.


#8

Worth noting several prominent Go people have expressed that having formatting options is bad: https://twitter.com/rob_pike/status/720423913851781120

(Personal note: I agree. However, seems inevitable until we decide what exacty those options should be. If 1.0 is configurable, I’d like to see a 2.0 that isn’t fairly quickly.)


#9

Personally, I think it makes sense for the official version of rustfmt to have no configuration options, while a version of rustfmt with configuration sticks around so that we can prototype new rules and (rarely) changes to the rules quickly.

The vast majority of people will use the official rustfmt tool, and we can include it with our official editor support and encourage other editors to use it as well.

I’ve been using rustfmt with vscode for a while now, and the fact that I press save and it “just works” without having to think about it has completely overridden any aesthetic concerns that I might have (with maybe one exception that might have been a bug). That probably speaks to the fact that the defaults are already pretty good.

I’d encourage people testing it out to use rustfmt without config (with editor integration), even if there’s something that you wish you could tweak, and see if the “save and it works” feeling doesn’t quickly come to override the urge to configure.


#10

I agree. In order for tool such as this be as successful gofmt, it should be used to remove personal preference, not enforce it. As we spend as much time, if not more, reading code than we do writing code, a goal of a code formating tool should be to make unfamiliar code appear familiar. Familiarity is key to growing an ecosytem.


#11

Not only would I have no use for an non-configurable formatting tool, it would make me feel unhappy for the Rust project to make official recommendations that people use one. I really dislike the Go language community’s position on this, which seems to be that it is on the face of it a poor choice to use a style which deviates from the official style, and I would not want to see that position imported into the Rust language community.

This text by Fat expresses some of my feelings well. It is very short and essentially all of it is relevant. Here are some other arguments that I am able to generate against eliminating configuration from rustfmt:

  • Styling choices are elements of a programmer’s self-expression. Having a recommended style for people who have no opinion is fine, having a tool which defaults to enforcing that style is fine, having a tool which is only useful to people who follow that style and promoting that tool amounts to a group decision about what kinds of self-expression through source code have worth.

  • Most people agree that within a project, a single style should be used for consistency. Even within an organization of projects, this is a sensible position. However, the advantage here is in producing code which is consistent with the style of the project, not in consuming code. At the level of language communities, most peoples’ source code exists for me to consume, rather than produce. In my personal experience, style differences do not usually impact my ability to read code.

  • I have only ever been unable to comprehend source code because of its style conventions when it was intentionally obfuscated code, in which case the deviation from official styles was an intentional part of the creative act.

  • I have never experienced disagreements about style as a significant distraction. I have not witnessed people at odds over tabs and spaces in a manner which damaged their project, and I suspect that there is a deeper problem with that groups internal dynamic if and when that does occur. Instead, I experience style disagreements as a harmless and even productive bonding performance in which we write exegeses about the One True Brace Style so that we might be better related in order to discuss matters which are “more substantive.”

  • I think allowing for heterogeneous styles is important for the same philosophical reasons that lead Rust to be a pluralistic and non-dogmatic language in other matters as well.

EDIT: Beyond rustfmt, I think there are fruitful avenues for experimentation in formatting tools which format on read as well as write, allowing each of us to use the style we prefer. Such tools would open up the possibility of even more radical experimentation by decoupling the representation of source on disk from the source we interact with.

EDIT2: In contrast, I have no objection with the style rules current enforced through warnings in the compiler, which seem like the “right amount” of styling to attempt to enforce to achieve consistent readability without denying heterogeneity of style.


#12

I think this may be a source of fundamental disagreement, which is interesting. In my experience, bikeshed discussions can be a huge source of distraction. The “bikeshed” phenomenon is really all about this fact.

It generally doesn’t result in fatal, toxic problems to projects, but it does waste a lot of time, and it’s a classic case where the cost of the disagreement far exceeds possible gains on either side of the disagreement.

I’m not opposed to the existence of a tool with configurability for people who feel as strongly as you do, but I’d like to give people a little nudge towards avoiding the disagreement in the first place.


#14

Having a separate tool seems less like a nudge and more like a speedbump. Why is the default configuration not enough guidance for new users?


#15

I have an unfiled issue / personal TODO to revamp the CLI user experience, so comments like this are great. Thanks!


#16

I think what makes bikesheds problematic is that they block progress on the actual product of the work: we can’t ship the language without determining the language’s syntax, for example. In contrast, disagreements about indent count don’t block anything from my perspective.

I imagine a difference in our feeling about this is that you probably have a certain level of responsibility to follow and steer even mostly irrelevant style discussions in Rust, whereas I can totally ignore them because they don’t impact me. Taking time from core developers is a nontrivial negative cost of style arguments, and it would make me happy for that to be relieved.

I think having moderate, sensible defaults is enough of a nudge to get most people to use it. :slight_smile: I think its also possible to enable configuration while also firmly disallowing litigation about changing the defaults.


#17

I would like to steer the conversation away from the configurability issue. I do think it is important, but it is not a decision that we’re in a position to make yet. (I’m personally undecided on the issue).

My priorities are to get Rustfmt working well for the majority of users (i.e., mostly bug free, a reasonable set of config options, with a reasonable set of defaults), then decide on a level of configurability and the default options, etc. Let’s restart the configuration conversation again in a few months.


#18

You’re right, this conversation should be delayed. Sorry!


#19

I think everybody is aware of the Go core team’s opinion, and I’m happy their strategy is working out for them. But just going by the wording of the tweet, to me it just sounds dismissive of people with different viewpoints. That tone is actually why I mostly stay out of the *fmt tool discussions now.

Edit: I apologize, while @nrc’s comment came before this, I didn’t see it until after I sent it off.


#20

I hope that my comment, while agreeing with the conclusions of the Go core team, do not have the same dismissive tone. I agree that their tweet felt more like armchair sniping than useful feedback.


#21

No, no worries, it certainly did not. But thanks for asking!