SE-0250: Swift Code Style Guidelines and Formatter

[stephencelis]

@hybridcattt

FWIW, I feel like most of those who care about consistent code style and maintain a large codebase already have some third party formatter set up on their projects.

FWIW, I think plenty more don't bother because of the overhead of introducing a tool that isn't at-hand. If tooling came with Swift it would be much more approachable. While I don't use any kind of formatter for my current Swift projects, I'd immediately adopt a first-party tool.

[Tino]

@allevato

I don't see how that conclusion follows at all

There is no conclusion, only two questions. One of them obviously is a hyperbole, but the important one is still waiting for a serious answer...

@allevato

Rather, let's presume that we adopt a formatting tool that allows some degree X of configuration. The situation is this:

• People are welcome to do whatever they want on their own projects. They may choose to adopt a set of recommended style guidelines, or configure the tooling to do something else, or choose not to use it entirely if it's not suitable for their needs.
• If a project stores its configuration in its repository, then new contributors don't have to worry about learning in advance a new style or having reviewers come back with a large number of style-based comments. The tool takes care of it for them, and both users are more productive as a result.

I don't think there is a need to presume anything:
Everyone can easily adopt a formatting solution and proceed as you described — without tedious proposals or reviews which slow down development of tools.
Why is an official tool so much better that it justifies all this trouble?

[hybridcattt (Marina Gornostaeva)]

FWIW, I think plenty more don't bother because of the overhead of introducing a tool that isn't at-hand. If tooling came with Swift it would be much more approachable.

Maybe my point was not very clear. What I meant was, that people who care enough to try out the styles while they are being developed probably already have a tool set up. I didn’t mean that the official tool is not needed because of existing third party ones, but only that it’s not needed right away to facilitate the initial proposals.

Anyway, @allevato gave a good explanation why it’s still a good idea to have it from the start. I am
officially convinced

Wouldn’t it then make sense to introduce the tool together with the first style proposal? Then the tool will grow together with the style, first supporting only the parts that each proposal contains.

If there was, say, a proposal for how to put spaces before and after colons, the tool would first have support just for that. With that approach, the community gets a chance to discuss whether each individual addition should be configurable.

This approach might require taking out some of the existing functionality from the tool proposed here, but I think there can be benefit in that.

[allevato (Tony Allevato)]

@hybridcattt

Wouldn’t it then make sense to introduce the tool together with the first style proposal? Then the tool will grow together with the style, first supporting only the parts that each proposal contains.

That was also carefully considered Ultimately, we didn't want to have the style guidelines be part of the proposal about the adoption of the tool into the project because we didn't want either topic to detract from discussion of the other if they were proposed together. I think it would have been more difficult to consider feedback effectively if we had gone that direction.

@Tino

Everyone can easily adopt a formatting solution and proceed as you described

This, I believe, is the "power user bias" that I also referred to in the pitch thread. And in fact, the post just above yours show one user who would like to have such a tool as part of his workflow, and despite being an experienced developer does not want the overhead of introducing an external one.

As both a software developer and a former educator, I think there is absolutely value in the Swift project providing an out-of-the-box formatting solution that doesn't require third-party packages or manual installation and which comes with a default configuration that would satisfy many people (but still provide some degree of customization for those who need it). That's a boon for audiences across the board—new users learning a language as well as experienced developers working on large projects (their own or on teams).

Folks are welcome to disagree with this, but my opinion is that formatting tools should be considered just as integral a part of a toolchain as the compiler and linker are.

[lancep (Lance Parker)]

Having a tool developed along with he style guide fits in nicely with Swift Evolution's rule that an implementation needs to accompany a SE proposal.

[xwu (Xiaodi Wu)]

@taylorswift

No, an analogy might be between different regional accents (northern/western US vs southern US for example), which are just as culturally sensitive and fraught with identity as differences in language. tino’s point stands.

This is needlessly hyperbolic. There are no issues with how one writes code that are “culturally sensitive and fraught with identity” like human languages.

[anandabits (Matthew Johnson)]

@allevato

That's likely true, but that's also where the part about swift-format being specifically staffed comes in. We wanted to provide a better follow-up to any impending "here are some proposed style guidelines" than an implied "you're on your own to figure out whether the tooling you already use supports them and to modify that tooling to try it out".

Nobody is going to stop you from writing a tool. In fact I think we all welcome you doing that. It doesn't need to be an official Swift project tool in order to be valuable. The existing tools developed by the community are a testament to that!

@allevato

By having the tool first, it puts the responsibility squarely on us—where it should be, if we're proposing style guidelines—to provide a great experience for users to try them out effectively.

You can fulfill this responsibility without needing the tool to be accepted as an official tool. You could work on a proposal for style guidelines which could link to any and all tools which are able to provide implementations of the proposed guidelines (including links to the necessary configuration for each tool as appropriate). This would let people evaluate the guidelines every bit as thoroughly as an official tool. If any 3rd party tools decided to participate it would also let people evaluate how the proposed guidelines work with a variety of tools (perhaps one that they are already using).

Taking this approach would not mean that swift-format will never become an official tool. It just means that it doesn't need to do so right now in order to accomplish your stated motivation for this particular timing.

[lancep (Lance Parker)]

@anandabits

It doesn't need to be an official Swift project tool in order to be valuable.

Yes, but it would be more valuable as an official tool. The added friction of installing a third party tool is definitely negative aspect of those tools.

[anandabits (Matthew Johnson)]

@lancep

Yes, but it would be more valuable as an official tool. The added friction of installing a third party tool is definitely negative aspect of those tools.

I don't disagree with you and I support having an official tool eventually. But I am skeptical about the timing and method in which a specific tool is being proposed.

The point of my post is that swift-format can play a nearly identical role in evaluating style guideline proposals no matter where it is hosted. The only difference is that users wishing to try out the proposed guidelines on their code may need to do an additional tool installation. I don't think that is an unreasonable bar for those who wish to participate in the SE review of proposed style guidelines.

[karim (Karim Nassar)]

Especially since anyone wishing to try out the proposed guidelines on their code who are already using another tool (e.g: Swiftlint) will need to undergo the extra steps of disabling formatting functions of those tools. We shouldn’t minimize the disruption that the introduction of a new tool will have on code bases and projects that already have overlapping tools in place.

[Panajev (Goffredo Marocchi)]

What is the point of putting this through Swift Evolution instead of continuing to work on the open source project as it stands?

Also, one moment it is useful and a real big problem when moving from project to project (which having an official style and formatter would fix) and on the other you do not expect and call toxic when existing projects that would cause the context switching are pushed by some of their members to conform to the “official” style... we expect this to change things significantly or not?

[Panajev (Goffredo Marocchi)]

Uhm... yeah, I think you reinforced the point there :).

[Panajev (Goffredo Marocchi)]

SwiftFormat is really easy to use and has very very sensible defaults, I would actually propose that one over swift-format in terms of speed and default formatting option.

[akyrtzi (Argyrios Kyrtzidis)]

Hi Goffredo,

@Panajev

SwiftFormat is really easy to use and has very very sensible defaults, I would actually propose that one over swift-format in terms of speed and default formatting option.

A formatter tool that is part of the swift.org projects should be using SwiftSyntax for its functionality. SwiftSyntax is directly integrated with the Swift parser and we are focused to keep improving in terms of performance and convenience for building Swift tools that need to understand the syntactic structure of Swift code. It has performance features like incremental re-parsing so that a live editor will do only the minimum work necessary to get an updated syntax tree after small user edits. Any change in the Swift grammar is going to be reflected in the SwiftSyntax APIs, either from the direct implementation of a SE proposal or at least soon after a proposal is accepted.

To minimize maintenance overhead it is desirable to have a clear separation of concerns for the swift.org projects. That means that the functionality of understanding Swift syntax is going to be provided by SwiftSyntax and other projects like SourceKit-LSP and a formatter tool are going to build their functionality on top of SwiftSyntax, instead of trying to duplicate it.
I'm mentioning this because SwiftFormat has developed its own lexer and parser and it would need work to rewrite significant parts of it.

@Panajev

in terms of speed

I'd like to clarify that the NSHipster article compared swift-format using swift-4.2 which only provides the slowest available way to get a SwiftSyntax tree (invoke the swiftc binary and parse a large JSON file) and SwiftSyntax itself did not have good visitation performance. SwiftSyntax in master/swift-5.1 has been re-designed and has orders of magnitude better performance in almost all aspects of using it, like parsing, visitation, incremental re-parsing, etc. Some details on how we improved parsing performance are in this forum post.

Another thing I'd like to clarify about a formatter project that is part of swift.org, is that it will aim to provide the building blocks for doing formatting rule transformations. Regardless of how configurable the resulting binary itself will be, the project will be a SwiftPM project and designed in a way that other projects can depend on its libraries to either use as is or modify its formatting pipeline or even plug in their own transformations. That will allow, for example, SwiftLint (which is doing a lot more than just whitespace transformations), to use the same building blocks and just focus on adding additional rules and functionality on top of the underlying infrastructure. They can be free from worrying about the particulars of handling a Swift grammar construct unless it is relevant for some particular rule.

[Tino]

@allevato

That was also carefully considered Ultimately, we didn't want to have the style guidelines be part of the proposal about the adoption of the tool into the project because we didn't want either topic to detract from discussion of the other if they were proposed together. I think it would have been more difficult to consider feedback effectively if we had gone that direction.

That sounds like a sugarcoated way to say "we wanted to avoid the terrible backlash from those who disagree with our preferences" ;-). Also, I don't buy the rationale:
What kind of detraction could happen when you ask the community simple questions like "how should indention look like?", accompanied with a small tool that can transform code according to the choices given in the proposal?

Imho SE-0250 tries way too hard to please everyone, and @hybridcattt's plan is more honest.
Of course, this alternative could pose a serious danger to the idea of incorporating an official (complete) style guide, because of all the unavoidable bikeshedding.

The proposal says that

This meta-proposal does not attempt to define any specific style guidelines

but at the same time, it aims to integrate an existing formatter that inherently defines a style via its defaults.
The text speaks about subsequent proposals to decide about the guidelines, but imho it would be completely nuts to adopt swift-format with its default style and amend it afterwards:
Do we really want to have an official style that changes every few weeks, until all options have been reviewed?

So in the worst interpretation, acceptance of SE-0250 will silently establish a set of rules with no ratification by the community at all - and if that is not the case, then building a new formatter and a official ruleset side by side would be much faster delivering usable results, because you could apply each rule as soon as inclusion is decided and added to the toolchain.

[SDGGiesbrecht (Jeremy David Giesbrecht)]

@Tino

So in the worst interpretation, acceptance of SE-0250 will silently establish a set of rules with no ratification by the community at all - and if that is not the case, then building a new formatter and a official ruleset side by side would be much faster delivering usable results, because you could apply each rule as soon as inclusion is decided and added to the toolchain.

That is not the case. The proposal author has said this:

@allevato

[M]y understanding is that the code would be contributed to the Swift project but that it would not be distributed in release toolchains until the community were able to discuss and ratify guidelines.

The proposed tool is a bare‐bones prototype—implemented enough to prove that it works. It has no rules beyond a few stand‐ins for preliminary tests. It is literally an attempt to, in your words, “[build] a new formatter and [an] official ruleset side by side”. @allevato and his team got the underlying framework ready before the pitch so that if it is accepted, the tool is ready to immediately start implementing individual rules as they are reviewed and accepted.

It may not have been explained that way clearly enough the proposal, but from talking to him and looking through the swift-format project, that is the understanding I come away with.

[hartbit (David Hart)]

• What is your evaluation of the proposal?

I've always been a big proponent of style guides, formatters and linters to help developers work together. I've also been a big fan of the Swift Style Guide that proposals authors have written. I therefore wholeheartedly hope this proposal will be accepted and we can move to the second stage of getting the Style Guide under review.

• Is the problem being addressed significant enough to warrant a change to Swift?

Yes. While discussing this topic takes a lot of energy from many people, I believe that the benefits from having an official Style Guide and formatter are worth it. While the guide will not satisfy everybody, I hope it will please enough people to cause a majority adoption and therefore harmonise the style of Swift code in the whole community. People can then move project to project with little syntactic friction.

• Does this proposal fit well with the feel and direction of Swift?

Not sure how to answer this question for this proposal.

• If you have used other languages with a similar feature, how do you feel that this proposal compares to those?

I have a fair amount of experience with PHP, where many developers follow the PSR2 formatting standard. And this has tremendously helped me to stop bothering about syntax and just accept the standard most projects use. But its not an official standard, so it still requires developers to install third-party tools to enforce. I believe there is a real advantage to having those tools come bundled with every toolchain.

• How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

In-depth study and read of the comments on this thread.

[IanPartridge]

@tkremenek

• What is your evaluation of the proposal?

+1.

I believe for Swift adoption to grow, focus needs to shift to improvements in tooling, the package manager, stdlib richness etc. rather than adding more language features. Adding a code formatter to the project is an important part of fleshing out Swift's tooling.

From an architectural POV, building on SwiftSyntax is the right direction so I don't object to choosing swift-format at this stage, although I think before it was actually shipped as part of a release the tool would need to prove its functionality, stability and performance in comparison to other formatting tools in the ecosystem.

I am happy for the tool to have as many configurable options as people want, provided the defaults match my personal preferences ;-) . More seriously though, I see that swift-format accepts a --configuration option which can be passed a JSON file. I would like the tool to automatically detect a swift-format.json file at the root of an SPM package, and use it automatically when swift format is invoked from that directory. If swift-format.json is not found it should look for ~/.swift-format (or something) and use that instead if found (forgive me if it does that already, I haven't played with swift-format myself yet).

Thank you to Google for bringing this forward.

[Tino]

@SDGGiesbrecht

The proposed tool is a bare‐bones prototype—implemented enough to prove that it works. It has no rules beyond a few stand‐ins for preliminary tests.

Imho that is an important information that should be more visible - but where is it actually coming from?
At a first sight, https://github.com/google/swift/tree/format/Sources/SwiftFormatRules does look like anything but rudimentary, and Swift Style Guide has a very long list of decisions that have already been made (including controversial ones, like the rule that you have to use two spaces for indentation).

The link says about the styleguide

It is a living document and the basis upon which the formatter is implemented.

I wonder why I haven't seen this link before… is this actually missing in the proposal?

[Jon_Hull]

I am a strong -1 on this proposal.

I would be happy if Xcode adds some configurable tools which help with formatting, but I have zero interest in having large style debates on Swift Evolution.

If there is something which lets my team setup and maintain a particular format for our particular project, that would be helpful... but defining a default for all of Swift would make me just not want to use Swift (unless the default was very close to my own preferences... which is unlikely).

Furthermore, I really don't want to spend our time and energy on this forum debating style guidelines, as opposed to actual features. I anticipate it making these forums more hostile than they already are.