SE-0250: Swift Code Style Guidelines and Formatter

Evolution Proposal Reviews
34

I do not mean removing functionality. I only meant converting any default validation or formatting to being opt‐in until they individually pass review. Otherwise we are effectively reviewing them now. (A reasonable alternative would be a guarantee they will go through review before they see release; then work must only be done to adjust rejected guidelines.)

For example, in a Unicode world I don’t even know what “line length” is supposed to mean. (Measured in clusters or scalars? What about scripts where the very concept of “monospace” is nonsensical?) If the community hashes out what it is supposed to mean, then I would be okay with having to opt out of it if the resulting decision seemed weird to me, but I do not want deal with that type of warning if it has not even gone through review.

I am fine with guidelines, and I am fine with swift-format being the starting point for the tool implementation, but I do not like the idea of swift-format being the starting point for the guidelines unless they are reviewed first.

2 Likes
35

I was very happy to see that the core team intends to consider feedback provided in the pitch thread. I won’t repeat what I said there other than to say I am happy to see a pragmatic perspective on configuration has been made clear.

There is some irony in that many of the strongest advocates of the style guidelines are those who claim to most strongly wish to avoid style debates. Yet acceptance of this proposal will inevitably lead to the most epic and detailed style debates the Swift community has ever seen. It’s a bit like starting the war to end all wars (this is especially true of those advocating an unconfigurable mandatory tool).

With that in mind, I definitely share the concern some others have expressed that this may not be the best use of time and energy for the Swift evolution community. If the reviews produce a set of default style guidelines that feels reasonable to the majority of Swift users the community would benefit enormously. But I don’t think that outcome is inevitable and I don’t think it will be easy to achieve, especially after people have spent years forming varying preferences.

On a personal note, I really don’t have much desire to spend time and energy debating style on Swift evolution. At the same time, as a passionate Swift programmer with well-formed and well-reasoned style preferences I know I will feel compelled to do so on style issues where I have strong opinions as it is unlikely style decisions will ever be reconsidered. I am probably not alone in feeling this way. The toll these debates could take on the community should be considered carefully before we decide to engage in them.

This is unfortunate (if you intend to merge the tool immediately upon acceptance of this proposal).

With all due respect, I don’t think this is a very realistic perspective. This tool will start to receive a lot more users once it is included in official Swift releases. Those users will often have a status quo bias for style decisions they are not explicitly dissatisfied with.

So the timing and method in which this tool is introduced into official Swift releases does matter and introducing the tool before the style guidelines have been reviewed will influence those future discussions and reviews. This will happen even if the proposal authors and core team do everything they can to prevent that from happening. The one action the proposal authors and core team can take to minimize the influence of the current defaults the tool has is to simply be patient and wait to introduce the tool until all of its defaults have been reviewed and accepted (and modified when necessary).

If the goal is to introduce a tool and see widespread acceptance of both the tool and its defaults I think it would best to review the guidelines it implements before the tool is officially introduced. Prior to that the tool can at best be considered a “beta” tool as it by definition cannot operate as intended (i.e. used to apply the recommended style guidelines). Swift has gotten by thus far without official style guidelines or an official formatter. What’s the rush to adopt an official tool before it is actually ready?

19 Likes
36

@allevato

Sure, I can.

The proposal contains the sentence "We propose this specific tool because it satisfies all of the following goals". That tool being https://github.com/google/swift/tree/format.

Such a sentence makes anyone able to turn votes for the proposal into votes for this tool. This is not quite correct. Most +1 here are not for this formatting tool in particular. They are for a formatting tool.

What if this tool is not a good fit for the future set of guidelines and rules the community agrees on?

This is why the proposal would be enhanced in this sentence and immediate context were removed.

Similarly, the swift-format tool hosted at https://github.com/google/swift/tree/format has been a visible part of the pitch/proposal from the initial draft and pitch thread, as it has been intended to be the specific implementation that is required for a proposal to reach the review stage.

You are totally right. I was blinded by the goal, and did not notice this specific during the pitch phase. I have nothing against your tool, but we have a logical twist when the tool is chosen before we know what the tool has to do.

If your concern is specifically about the changing of the wording from "intend to propose" to "propose", the sole factor there was that we felt "intend to propose" was appropriate for the pitch phase (because it was a pitch, not a proposal), and that "propose" was appropriate for the actual proposal.

Thanks for writing this. I do think that the proposal intent will be better expressed in the tool choice is explicitly listed in the deferred decisions.

2 Likes
37

@allevato

I'm more and more confused, actually. Is this actually a proposal for Google's formatting tool? If yes, why isn't it written front and foremost? Why aren't other formatters listed as alternatives?

1 Like
39

I'm +1 on a default Swift style but -1 on swift-format as the tool to implement it.

Overall I would like to see some set of styling integrated into Swift's tooling, both in the hope that Xcode might finally have configurable formatting, and in the more general desire that we can develop Swift on all platforms with consistent formatting. I would hope that such a formatter could integrate with the upcoming LSP implementation so that formatting can be separated from the editors used to write Swift.

I also think some common styling defaults where not everything is configurable could be fine, if the community can approximate some sort of consensus about them. It makes sense to me that there would be some formatting rules which are configurable (line length, function wrapping behavior) and some that aren't (brace placement, colon placement). We'll see how that discussion goes. Like @anandabits, I anticipate quite the discussion.

However, as it stands right now, swift-format is the inferior formatting tool and I'd rather see a community tool integrated instead of a lesser but Apple blessed tool. Most notably, the use of a JSON configuration file is both a poor choice from a user perspective (JSON is a pain to write by hand and is really only better than XML for config files) as well as the long term flexibility of the project (JSON types are inherently limited). I also find it funny that, at least for now, it's not the best performer, despite the proposal's claims. If adopting a community tool is impossible for some reason, at least adopting YAML or TOML for the config file would make it more acceptable to me. Then we just need to hash out the actual styling.

3 Likes
40

Continuing the discussion from SE-0250: Swift Code Style Guidelines and Formatter:

-1

  1. We propose formally adopting a formatting tool into the Swift project that will allow users to update their code in accordance with those guidelines.

I do not support an official tool that only enforces a single recommended style and has no room for local/team based customization. The reasons provided in the pitch comment here Pitch: an Official Style Guide and Formatter for Swift - #202 by haikuty still stand.

In particular,

One thing to consider is that some individuals have visual impairments and need some extra spaces in the code they write to be able to visually parse it. If you make a strictly enforced style guide agreed upon by the majority then you will almost certainly leave those with accessibility challenges out in the cold suffering.

An official tool that only supports one format will become the de facto standard and Xcode and other tools are unlikely to support using alternative formatting tools as easily. This will make it more difficult for individuals who need a format different from the single, majority-defined, one supported by the default tool to advocate for their needs. The Swift project should not be making it harder for those with disabilities or wither needs outside the average/majority to participate in the community and profession.

Make it configurable or don’t do it. There are enough third party formatters that already exist to prove it’s not impossible - nor even particularly difficult - to do so.

4 Likes
41

I'll preface the following question with a disclaimer that even though this has been collaborative work, since I'm not on the Core Team, it's not my place to make any assertions about how toolchains will be packaged or distributed.

Can you define what "official Swift releases" means, in your mind? For example, would you be opposed to it being distributed with any snapshots of the toolchain? Would you be comfortable with it being distributed with trunk snapshots, but not release snapshots? What if it were in a separate repository and users built it from source until the style guidelines have been ratified?

Based on feedback so far, I think there's a concern from some users that if this proposal is accepted, that swift-format as it is implemented today will be dropped into everyone's toolchains as a precompiled binary and that it will be unable to be changed. That's not what would happen here; my 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.

Thinking about this more, I wonder if our disagreements are purely around different interpretations of what the word "adopt" means, and that we should attempt to clarify that. It's certainly possible that, as proposal author, I'm assuming that other readers would interpret it the same way when it's actually open to more possible interpretations than the one I intended.

3 Likes
42

The current version of the proposal was updated based on feedback around this in the pitch thread (for example, these changes). Do those modifications not address your concerns fully?

43

What is your evaluation of the proposal?

I would love to see Swift get an official formatter. The cumulative time saved trying to maintain a consistent style across a codebase/project/team/community would be a huge win. A formatter would directly lead to benefits 2, 3, and 4 in the motivation section of the proposal.

A style guide will undoubtedly end up leaving room for interpretation and would still require manual monitoring/enforcing. I'd be surprised to see it not contradict the formatter in some fringe cases. I'm not sure a guide gives any additional benefit over a formatter.

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

Yes. Again, the benefits listed in the proposal can save a lot of cumulative time manually formatting and reviewing code.

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

Yes. Being part of Swift would give us consistent formatting across Apple's open source Swift projects and guide newcomers to format the same way. Enabling third party formatters would not have these strong benefits.

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

Yes.

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

A quick reading.

1 Like
44

To be fair, the proposal does not claim it's the best performer, simply that using SwiftSyntax is both a reliability- and performance-based decision; much of that performance will be realized with the new parsing APIs that are being introduced with (I believe) Swift 5.1.

I tried to address this in the pitch thread, but we made the conscious decision to use JSON because we wanted to avoid pulling in third-party dependencies to avoid licensing concerns at this time. So, Foundation limited us to JSON or XML. I'm quite happy to revisit decisions such as these, and I hope that they wouldn't be used as reasons to reject the work; the tool is by no means static. (I also think the "pain" of JSON is a bit overstated, IMO. I update JSON config files for Visual Studio Code much more frequently than I would update a formatter configuration, and it's never found it to be that troublesome.)

1 Like
45

I'm more concerned about the flexibility of the format than reading or writing, but I don't find "I do it all the time" a particularly compelling response. I mean, I have to edit plist XML files all the time, but that doesn't mean they're not a strictly inferior format and that, when I do have to edit the files, it wouldn't be much easier to read and write if they were YAML. But JSON is very limiting (or perhaps just more complex) when it comes to supporting anything that can't fit easily into a JSON type.

I also find the licensing concerns to be very strange. Could you be more specific? Swift already relies on and uses a variety of open source libraries and tools. I'd think there's a YAML library with a compatible license out there. Or is this Apple legal's concern, and not a developer concern? Swift will continue to have strictly inferior tooling if it can't use anything the community builds.

46

In general, I don’t mind if trunk snapshots include an unreleased tool, but the release snapshots should not include an unreleased tool until it will be included in an upcoming release.

I also think the sentiment expressed by @gwendal.roue is appropriate. This proposal claims to be a meta-proposal, but also proposes a specific tool that happens to be in the very early stages of development.

After reading Swift Code Formatters - NSHipster and learning more about where it’s at, it feels extremely preliminary to me to propose this specific tool. It looks like it has a long way to go to achieve acceptable results. Opinions may vary of course, but I find the output of Prettier to be far superior to the other tools presented by NSHipster (it actually happens to be what I would write manually modulo documentation).

I’m sure your team is very capable of developing a tool every bit as good as others, but how long will that take? What if the reviews of specific style guidelines produce results you aren’t expecting? Is it possible this will create implementation and / or performance challenges (see the comment on NSHipster about the performance of Prettier).

It feels like we might be putting the cart before the horse by front loading official tool selection into the meta proposal. I don’t think it’s fair to call the current tool an implementation in the usual SE sense at all. An actual implementation would have to implement recommended style guidelines which don’t exist yet. Why not review an official tool last after all (or at least initial) style guidelines have been accepted and we can evaluate the tool against these guidelines (as well as other considerations)?

At the same time, I think it’s reasonable that the Swift project try to use tools that already ship with Swift in the implementation of an official formatter, which is one of the stated motivations for starting with this codebase. So I don’t have any objection to this codebase eventually becoming the official formatter, it just feels preliminary to be asked to evaluate whether that would be a good decision or not.

9 Likes
47

One option could be using Swift for configuration. swift-format can potentially share some of SwiftPM’s infrastructure.

5 Likes
48

To my knowledge, no other projects currently hosted on Apple · GitHub that use SwiftPM point to package dependencies that live outside the Apple · GitHub organization. Since I'm not an employee of Apple, I felt it important to not make any assumptions about what third-party libraries I could or could not use for a project that I was proposing they adopt.

If the work is adopted and those licensing concerns are not a blocking factor, then as I said, I'm more than happy to look at other options. There may be some precedent here; Apple forked cmark into swift-cmark. But understand that legally, it's not my place to make these decisions unilaterally.

Orthogonally, there's the possibility in modern package-based software development that a remote dependency you rely on can just disappear if the maintainers choose to do so. Is the risk of that happening low? Possibly. But it's still an important factor to weigh.

49

Thank you. That answers my question and seems reasonable.

1 Like
50

we have a logical twist when the tool is chosen before we know what the tool has to do.

Accepting swift-format in the swift project is about accepting a capable and malleable tool that will evolve along with the Swift style guidelines discussions. It will be conveniently available and easy to try out to see how specific rules affect the sources in your projects. We could have separate PRs for implementing particular rules for which a swift-ci invocation could create a zipped binary for mac & linux that you can use to evaluate a particular rule on your own projects.
swift-format itself will help facilitate the discussions.

Tony and his team are available to do the work for a formatter tool, written in Swift, that will adhere to the style guidelines and benefit all of the Swift community, and any interested party can help contribute as well! It is about a tool developing and evolving in the open, not about accepting a ‘set-in-stone’ tool.
Certainly I don't think a tool written in JavaScript is what the Swift project should adopt.

7 Likes
51

I'm not sure why you are +1 then:

The proposal authors wish to emphasize that we are not proposing that users be required or forced to use a particular set of style conventions. The Swift compiler will not be changed in any way that would prevent otherwise syntactically valid code from compiling. Users who wish to reject the style guidelines and adopt a different style for their own projects are free to do so without the tooling pushing back on that decision.

While this does explicitly call out "tooling pushing back", I think it would still violate the spirit of this paragraph to have the community make these recommended conventions quasi-mandatory. Or am I misunderstanding the proposals intention?

3 Likes
52
  • What is your evaluation of the proposal?

I’m very positive. I believe that this has the possibility of silencing many boring discussions about style choices (after the one big discussion has been taken in these forums).

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

Yes, I believe so.

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

In the sense that similar code styles will give better readability across code bases, yes.

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

NA

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

I’ve read most posts in the pitch thread and joined the discussion. I am using existing (phenomenal) formatters and linters already, and the goal of consistency by using these are the same.

1 Like
53

I think the changes made during the pitch phase are great, particularly the wording around configurability, and I support the resulting proposal (with the additional in-thread clarification about what “adopting” swift-format means in this context). I think the concerns about configurability defeating the purpose of such a tool are overblown, and I think the default style would be widely adopted by virtue of being the default.

54

What is your evaluation of the proposal?

+1 -- for the style-guidelines
+1 -- for a format-tool using LibSyntax or SwiftSyntax (I don't know much about the one proposed however)

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

It sounds beneficial but not urgent, so assuming development doesn't impact higher priority efforts it seems like a good addition.

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

Yes. Swift has declared itself to be opinionated. Ideally it would make adhering to its style-guidelines easy, but leave other styles possible.

Judging beauty and elegance of style is subjective, but there are big benefits if style-guidelines are predictable and consistent.

The recent embryonic discussion of Swift in a non-English language may not ever come to fruition, but it shows Swift-interest from people whose native tongue isn't English. IMHO. even before becoming fluent with Swift's keywords, predictable, consistent styling helps to visually reinforce and aid learning.

Even if you're an experienced Swift developer, consistent style-guidelines that expose an unexpected formatting can help diagnose problems with code validity.

Assuming the code is valid, predictable style-guidelines also reduce clutter and let you focus just on what the intent of the code is.

Unexpected formatting is cognitive noise, and as style-guidelines become more universally adopted, the more consistent ones expectations become, and the more cognitive-noise can be reduced.

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

I hesitate to bring this up, but if you're familiar with the wealth of BASIC environments on old 8-bit computers (TRS-80, Apple II, etc), those are simple examples of style-guidelines that most would say were ugly, yet they were still helpful through their consistent enforcement.

The platform's style wasn't a requirement for valid entry, but the BASIC environments enforced their platform's style after entry. A motivated developer could still use other tools to develop with a different style, or toy with tricks in code to appear to vary from the platform-style. Despite those options, most programmers got quite accustomed to predictability of a platform style. So as ugly as the style was, it helped debugging because of the standardization. Even in printed magazines or books, one would find the ugly-but-predictable platform-style even when they could have changed to more attractive style-guidelines.

BASIC environments aren't terribly comparable to Swift; I merely thought it was relevant to mention the benefits effects of even an ugly set of style-guidelines.

1 Like