Pitch: an Official Style Guide and Formatter for Swift

(Cory Benfield) #222

If we want formatters to be nicely integrated into the tooling, we can do that without requiring that Swift ship a formatter. If we assume "the tooling" to mean IDEs and the swift command line binary, then I have good news. If a formatter places itself on your $PATH with a name like swift-format then the swift command line binary will automatically treat it as a sub-command implementation that can be run by swift format. For IDEs, the usual place to provide formatters is as a save hook: any hook in an IDE that could run an official formatter can run an unofficial one.

What no-one has laid out is what the specific advantage is of having the Swift project ship a configurable formatter that has not been addressed by third-party formatters. Let's use your follow-on paragraph:

Why is this better than having one, non-configurable default formatter, and then the currently existing open source ecosystem of alternative formatters? What benefit is obtained by having the Swift project attempt to serve all masters by providing a complex tool that supports arbitrary configuration flexibility?

The tool that you suggest (whose feature scope is "anything else we might want") is a profoundly complex beast. It provides only one utility over my counter proposal to just use a different formatter, and that utility is that "everyone runs the same command in their shell". In a world where we have invented symlinks, I don't find that advantage compelling.

So let me ask again: what specific, concrete advantage is provided by Swift shipping a configurable formatter, vs relying on the open source ecosystem to handle this problem?

(Boris Triebel) #223

I think we should want that.

I do not care about the "Swift project shipping" it part. I do care about a) configurable b) integrated c) officially supported d) having it as an accepted practice in the community to use it that way and not being labelled a fringe thing for people who intend to avoid the officially endorsed "normal way".

Thats basically it.

And by integrated i don't mean getting a 3rd party tool from GitHub, hooking it up in one of 5 different ways, editing config files. Putting files in $PATH, etc. In the year 2019 it should be integrated into the IDE just like you want powerful refactoring and debugging tools inside the IDE. Imagine asking for refactoring in Xcode and being told you should just install this helpful tool and do this bit of configuration work and every time do 3 steps to refactor something instead of just pressing a key and getting a sensible context menu. No way, right? For people who prefer or are forced to live in the terminal there should be a way to run it from there, obviously.

(Cory Benfield) #224

What does "officially supported" mean if not "shipped by the Swift project"? For that matter, what does "integrated" mean if not "shipped by the Swift project"?

Regardless, I understand your argument. Fundamentally the tool you want is something close to what mix can do for Elixir, though I think mix is not quite configurable enough for your goals. Alternatively, more like rustfmt but provided by the language.

I think if the Swift maintainers and @allevato's team are happy supporting something like rustfmt, that's great, go ahead. We'll use it, set to its default settings. I just want to note that I think many people in this thread will be disappointed by that tool: the odds of it supporting the quirks of everyone in this thread are approximately zero.

(Xiaodi Wu) #225

Given two completely interchangeable things A and B, if Swift supports both today, is it your opinion that Swift should never prefer or encourage one over the other in any way? I am not sure how you are in support of any style guide or formatter in any form then.

(Gwendal Roué) #226

@taylorswift may not be interested in the style guide, indeed, but may still be interested in the formatter as a way to enforce personal customs and traditions.

(Xiaodi Wu) #227

Sure. Keep in mind, however, as @lukasa has said, that "the odds of [the formatter] supporting the quirks of everyone in this thread are approximately zero."

(Matthew Johnson) #228

I don’t think anyone is arguing for this. The default style would in fact be very opinionated. I suspect most of us would prefer to stick close to this default style, but there will inevitably be some decisions it makes that we don’t want to be pinned down on. The specific decisions and rationale for wanting to deviate from the default will vary from project to project.

The existing open source ecosystem provides some excellent tools. However, it cannot and will not ever set a baseline in the form of a default style that is shared by the entire community. Further, the defaults that do exist in these tools have been chosen by their authors rather than discussed and reviewed here on SE.

Aside from defaults, I also believe there is merit in having a standard tool that ships with Swift. This means it is available to all Swift projects with no additional downloads, maintenance, configuration, etc. This is a nontrivial benefit which increases with configurabilty because it would be applicable to more projects, including those that are unwilling to follow the default style 100%.

That said, I think @nicklockwood’s concerns about this tool not receiving the attention it deserves are valid. Done right, an official tool would channel the community’s energy and therefore be of higher quality than could be achieved via independent competing open source projects. Done poorly, a standard tool would be unfortunately limited relative to competing open source projects but would zap the energy and motivation to continue developing those tools.

I think it’s important that if we do tackle an official tool we are committed to doing it right. Realistically, that means the organizations that propose the tool should be willing to commit to investing the engineering resources necessary to do so. It must be a best-in-class tool by any reasonable measure. Anything less would be harmful.

(Gwendal Roué) #229

Yes. And it will be another topic, discussed in another thread, right on its time, according to the schedule of this ambitious meta-proposal :-)

(Gwendal Roué) #230

Yes - we usually avoid talking money or time share or Xcode team in those forums, but it is quite close from the surface in this thread.

In this regard, we can compare the Swift formatter to SPM. A big ambition and a crowd of developers hungry for it, but slow to deliver and change everyone's practices. Please take no offense: SPM is alive and moving.

The lack of any information about resource allocation makes it actually difficult to discuss the Swift formatter. For example, of course I'd be happy to support as much configurability as possible. But if this project is as gifted as SPM, I'd rather avoid any kind of configuration, and focus on a minimum viable product. This does not make the task easy for you, @allevato :sweat_smile:

(Matthew Johnson) #231

If this project is resourced similarly to SPM I’d rather avoid the project altogether and just continue on with the tools we already have. It would still be possible to document style guidelines just as we have for API design guidelines. We could even provide configurations implementing these guidelines for popular open source formatters. But I think an official-but-resource-crippled formatter project would be harmful even with an MVP focus. The harmful effects derive from its mere existence as an official, but subpar, tool.

(Gwendal Roué) #232

I'm certainly more optimistic than you are. What you call a "official-but-resource-crippled formatter" may be a wonderful tool that does one thing and does it remarkably well.

(Matthew Johnson) #233

Perhaps, but it could also do the same thing in an unofficial capacity without the risk of harming the energy going into the tools we already have that meet other needs. What is the motivation for making it an official tool if we do not intend to provide resources to make it a tool that meets the needs of most Swift users in its domain (formatting in this case). IMO "official" tools should be intended to meet the needs of most users and should be resourced accordingly. If the resources are not available, what's the rush to declare it "official" and have it ship with Swift?

(Tony Allevato) #234

I think one part of this discussion that might not be getting enough attention is that everyone probably has a different definition of "configurability" when they say "the formatter could be configurable." But it's not a binary choice—it's a spectrum:

  1. A rigid and unconfigurable tool that ignores any user-provided whitespace except for the minimum required between adjacent tokens, essentially converting code to a single canonical form
  2. #1, but respecting user-provided discretionary line breaks so that the user has some control over readability with regard to line wrapping
  3. #2, but allowing for adjustment of a limited set of configuration options for practical reasons (like line length or indentation size, since some IDEs have constraints when working in multi-language projects)
  4. #3, plus some additional but still limited set of options
  5. A tool that allows users to configure literally every decision it makes regarding where to place a given token.

Folks so far have spoken up in favor of just about each of these, so it's not quite as simple as "should it be configurable, yes/no".

Obviously nobody can predict the future to a perfect degree, and I personally can't make any statements on behalf of Apple, but I can say that my team at Google (who builds our Swift support for Bazel and has made numerous contributions to parts of Swift) is committed to continued support of our tool. It has a large user base here so that alone is motivation to support it, but we would also not propose simply throwing code over the wall and calling it a day.

This is oversimplifying the problem space quite a bit. It requires that:

  • Any tool that wants to hook into this provide the same command line interface, and possibly the same minimum configurability characteristics
  • It presumes that the owners of those environments are willing to or able to provide those hooks
  • It ignores the possibility that those environments may want to do formatting in-process instead of spawning an external process, in which case you now have a resilient API design problem instead of a launch-an-executable problem
  • It also doesn't solve some of the original motivations, one of which is to provide a solution for the average user who just wants a common problem solved for them without having to seek out, evaluate, and configure alternatives.

I think in some ways there's a power-user bias; those who want to configure things exactly the way they like them are probably going to be disappointed by any solution we could present here. They're free to use something else if they wish, as is their prerogative. But that's not the only audience that we need to consider. There are a large number of individual developers, teams, and companies who want something That Just Works™ and performs reasonable behavior (either by default, or by design) without adding numerous extra steps to their developers' setup workflow.

(Matthew Johnson) #235

Absolutely, which makes it difficult to evaluate whether we like the pitch or not even with a concession to configurability. I probably fall somewhere into camp #4 but that depends on what is and is not included in the "limited set of options". That said, control over line breaks, line length and indentation gets us pretty far. As mentioned upthread, I think it would be acceptable to omit configurability on style issues where there is a clearly dominant style in the community. (Which of course begs the question how do we determine what is "clearly dominant" - on that topic I don't have an immediate suggestion)

(Cory Benfield) #236

To be clear, I agree. I'm not proposing a "magical super tool": I'm in the camp of wanting zero configuration in the default tool. However, I also think that if users value flexibility they should demand that of their IDEs. Power users are capable of configuring their IDEs: developers that want "Just Works" get a tool that is highly likely to work because it does not have the burden of configuration management code.

(Jacob Williams) #237

This thread has changed my original mentality and I am now opposed to making a "default" style guide unless it is the "official" style with an accompanying non-configurable tool. After reading through every single post in this thread, I believe the overwhelming majority of people who have posted here have either stated strong support for a non-configurable tool or have stated that they like configurability, but would just get used to having a single supported style.

I wholeheartedly agree with the sentiment of this paragraph. What is the point of coming up with yet another tool to do the same thing that's already out there?

I get that having one automatically integrated into the language would be nice, but adding something to your $PATH really isn't hard (most installs automatically add their executables to a $PATH location anyways) and configuring something in your IDE isn't either (almost all IDEs support the kinds of plugins/hooks this requires). If you want a configurable tool then you're going to be configuring stuff anyways so is requiring one or two extra steps of configuration really asking too much?

If you want a configurable tool, you already have several choices. They just require some configuration...which is what you want anyways isn't it? This is coming from a frequent user of SwiftLint where all my swift code is run through the linter automatically when I compile my projects.

I would disagree. All the hook really needs is a command line interface. How many IDEs supporting hooks like this really care how the command works? They all just require a command to call. Most allow you to even specify the arguments for the command in the hook configuration. Or if your command supports a configuration file, then you just need to make sure it's in the right place and has the proper name.

I would add that I doubt the average user wants to do any sort of configuration, and what's the point of a configurable tool for the average user that will never configure it? If we really want to actually help the average user that just wants to write code and not worry about style, then make an "official" style guide and non-configurable tool that will handle the style for them. If the average user doesn't want to learn how to configure a 3rd party tool, then why would they care about configuring the built in tool? Why make another competing standard? (Sorry for linking to the same comic twice)

Or we could just do nothing and let them write code however they want. Who says they even need a style guide to do that? That's where we're at currently at it seems to work just fine. I see no reason to push for yet another configurable tool when there are already several alternatives. If you don't care enough about having a style guide to follow then you're not going to learn how to configure the built in tool and there's no point in making it configurable. If you do care enough about having an enforced style guide then I bet you're going to go out and evaluate all your options to determine the right tool for the job.

I fear that the few exceptionally opinionated on both sides may overcome the majority of people who really don't care enough to fight either way. If it's configurable then they'll use it. If it's not then they'll live and get used to it.

Most people like to code the way that feels natural to them, but are not so dependent on their own style that they couldn't become accustomed to a new one. I am in that same boat. Many people also feel that having a non-configurable tool would eliminate much of the personal preference fights that occur on teams when writing their own style configurations.

I strongly believe that if there were a non-configurable "official" style guide and tool that within a year everyone would just be used to it. There are always people who will fight against a language being opinionated about certain things (look no further than the repeated pitches/proposals to add integer indices for subscripting String). While it would be nice to code however the heck I wanna, I can sacrifice a few of my personal preferences to conform to a uniform style that would make reading any and all swift code just as easy.

(Rudolf Adamkovič) #238

Should there be an official style? Yes.
Should there be an official formatting tool that enforces this style? Yes.

I am sick of having to think about (and talk about) tabs, spaces, parentheses, colons, etc. What a colossal waste of time! I want to focus on architectures, modules, interfaces, data, etc. Not some typewriter settings. So I say bring it on!

Ideally, the official formatter would have zero configurability, i.e. this is the one true official style; no more discussions about e.g. how to tweak its million settings, etc.

(David Catmull) #239

If, hypothetically, it is decided to have an official non-configurable tool, I think it's a fair bet that there will be at least one configurable unofficial alternative (especially since, as mentioned, there are already a few tools that are pretty far along). It's also a fair bet that such tools would also support the official style, as a built-in configuration option if not the default. I think that would somewhat reduce the popularity, and therefore the usefulness, of the official tool.

One option is that the official tool could be non-configurable in its "1.0" form, and options could be added later on.

(Pedro José Pereira Vieito) #240

Exactly, for the first iteration I would prefer a non-configurable formatting tool. Then, if the community sees the need for it, we could add some level of configuration.

(Pedro José Pereira Vieito) #243

Ups, my bad! Thanks for the correction!