Pitch: an Official Style Guide and Formatter for Swift


Official tool to enforce this but also allow certain overrides to defaults possible.

(Johannes Weiss) #102

I personally don't care about the style guide/tooling too much but I want to point out that I don't think the tooling part of the question in this pitch is precise enough:

Many people here mention gofmt as an example that worked well. But AFAIK, gofmt's big deal is to not have options, ie. it can't be configured, there is only one style. Others seem to assume that the official Swift formatter would have options like SwiftFormat and SwiftLint do today. Example: Two projects can both be using SwiftFormat today and have different indentations (eg. 2 spaces vs 4 spaces), but two projects using gofmt will always have the same indentation.

@allevato apart from if we should have a style guide, are we discussing whether

a) to add a Swift formatting tool to the Swift distribution that can be configured (ie. it would just be the promotion of swift-format, SwiftFormat, or SwiftLint), or
b) to add a Swift formatting tool to the Swift distribution that cannot be configured (like gofmt), or
c) it depends on the discussion here in which case I think we should ask if people prefer (a) or (b) explicitly.

(Frederick Kellison-Linn) #103

Yep, this is what I was getting at in my comment above. I think a setting that enables programmers to view and write code in their preferred style without interfering with a repository’s or team’s standards is the holy grail of any formatting tool. Removes the debate but also doesn’t force anyone to write/read code that feels “weird” to them.

(Pedro Carrasco) #104

Should there be an official style? Yes.
Should there be an official formatting tool that enforces this style? Yes. Although, people should have the option to define custom rules.

(Karsten Bruns) #105


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

A) I think a standard that is discussed in the community will free a lot of times in teams around the world who will not have to talk about this anymore
B) Long-term I see IDEs rendering code in a way that is different then how it is saved on disk (Plugins often already allow you to change tab/space-preferences to your taste in your IDE but they save the file according to the project standards) But I think it can go further. F.e. a future Swift IDE for Education could look more like Scratch, but for this to work we need a way that the resulting code, can in parallel opened and edited in other editor (At least that would be desirable). So long story short: Code formatters are an important step to separate the presentation on disk from the presentation in the IDE. This is IMHO groundwork for advancing the tools we use to code.

(Tony Allevato) #106

If this kind of workflow is a "holy grail", then why do you think it has never taken off in any serious manner in the software development community? All the tools needed to use a workflow like this exist today—at a minimum it's just telling your source control system to run a formatter that transforms code on checkout and commit. My gut feeling is that this isn't as universally desired a workflow as it is for its advocates.

Prefacing that this is my own personal experience and YMMV: On a personal project I can understand having a preference for one style or another, but in a team environment I've never felt so strongly about a personal preference that I've wanted to have it reflected locally over whatever other style guidelines may exist. All I care about is letting the tooling do the work for me, and I can adjust as I shift from language to language or what-have-you.

So why advocate for an official or default style? It lowers the barrier of entry for newcomers (either to the language or a particular project), reduces communication barriers within teams and beyond, and by defining some best practices, it means others don't have to have these kinds of debates ad infinitum (unless they really choose to, in which case, we can't stop you). Having an official style doesn't prevent people from doing their own thing if they want, but it does enable folks who just don't care either way to remove style concerns completely from their equation. It's a net win.

Circling back to the local-personal-style workflow, this is mentioned in "Alternatives Considered", but the that workflow falls apart if you're using any systems other than the particular IDE or source control system that supports this workflow. If you upload your code to a code review system, what does it look like when viewed there? Does it use a canonical style defined by some set of style guidelines? If so, why not just use that style everywhere? At least then everyone on the team has exactly the same view of the code, and basic concepts like "Can you help with a problem I have on line 104" don't pose awkward communication barriers.

Ultimately, as I alluded to above, I think the idea of a local-personal-style workflow is out of scope for any possible proposal we could craft here; it requires more support than the language and its own tooling can provide. We certainly can't gate decisions here on support from Xcode, because Swift is a multi-platform language and it shouldn't have decisions tied to one particular IDE or platform.

(Karl) #107

Should there be an official style? Yes.
Should there be an official formatting tool that enforces this style? Yes, but it would be nice if it was configurable.

I think I most closely align with @millenomi's point about considered deviation from the rules.

(Frederick Kellison-Linn) #108

Yeah that makes sense. Perhaps “holy grail” was a bit too hyperbolic, but it’s something I personally would love to see from Xcode. In any case, my support for an official style and formatter remains. As I have read the discussion I’ve also come to support a non-configurable formatting tool. SwiftLint et al will continue to exist for teams and individuals who find the official style so objectionable that they cannot integrate it with their workflow.

I think a lot of the objection comes from people who are unsure of the language that would be adopted around this feature, and I think that’s worth discussing as part of this pitch. There’s a lot of room between “We think these are some best practices when writing Swift” and “This is how all Swift code should be written.” Even though forcing style via the compiler is not on the table, the philosophy of what an official style guide means is important and will have an effect on its use. Stronger language will likely result in more adoption, but will make every style decision far more controversial. Do you have thoughts about what the “marketing” of swift-format would look like?

(James Berry) #109

Ok, I'll add to the chorus of replies.

I think that some of the objection to this pitch is just about pure semantics, but I also believe that semantics are important. I, and I believe others, would be more comfortable if we were to call this a "default style" rather than an "official style". Part of the problem with calling something "official" is that it brings up the fear that soon there will be "officials" enforcing that style, or that such a proclamation will make it all too easy to attempt to enforce that style at the expense of individual choices.

I'd happily support creation of a "default" style set and tools that could support that default style, as well as others. The default style would be used by default for expansion of templates or a when request is made to format something, etc, but could be overridden as suggested by @allevato, by local choices at the directory, project, or profile levels.

I've looked at the google swift-format code and it looks like a well-written tool that can easily be extended to be configurable: I think it's a great starting place. I think too that it could/should have configurable and switchable style-sets, the default of which might be org.swift.default, but which might over time come to support com.apple.foundation or what-have-you.

With that preamble, I'll put in my two-cents:

Should there be an official style? Yes, but please call it a "default" style instead..
Should there be an official formatter tool that enforces this style? Yes, but it absolutely needs to be configurable to support arbitrary local choices.

(Erica Sadun) #110

I heartily endorse Swift linters.The SwiftLint project is doing a great job. Their design allows developers to opt in or out of rules to customize house style. A vibrant and active community contributes to and supports this tool.

I support and encourage pretty-printing formatters, so long as they accept arbitrary customizable style sheets, and can apply them accurately and consistently for mechanical application.

The swift-format prototype does not reflect the depth, flexibility, and maturity of the Realm project. As we have already opened Swift forums to third party projects, why not go with the more evolved solution as the first tool to reach for rather than a passing mention?

I firmly disagree with "one style to rule them all", even in a minimal adoption. As a concrete example, I think LLVM style is not the best style for teaching, or for many development groups who use the extra whitespace for clearer code reading. Do we want to draw the line at 2-space vs 4-space indentation? Do we really want to rule one way or another about trailing commas in collections? Who makes the call about whether a unicode identifier has a "clear and legitimate meaning in the problem domain"?

The scope of the "official Swift style" must be narrow by nature. There's much more to style than 80-120-unlimited file lines and whitespace trimming. The Google style sheet is fairly limited, and best practices will vary between development groups. Style guidelines have to make some major decisions like "mandatory self", numeric literal formatting, consistent digit extent, functional-and-procedural parentheses (via @Lily_Ballard) , Boolean logic tests (for example, I prefer to leave my tests as direct results but @davedelong uses comparisons to true and false to better visually document the intent of the test). It's a minefield.

And in being a minefield, one can take the SwiftLint approach, which allows rule configuration and rule expansion, or one can bring google linting under the Swift umbrella and give it official sanction. In doing so, you will be necessarily limited in scope, have a much higher barrier for what can be included, and essentially conduct a technology transfer away from the community and towards the core team.

I'd prefer to bless and support SwiftLint and provide it with manpower and resources to continue its mission.

  • +1 for a default Swift format
  • +1 for a swift-format tool, ideally one that offers zero configuration, like gofmt and elm-format

I think this is the crux of the current discussion. People are getting hung up on "official style guide" and I think it might help to reframe/rename the thread/pitch in order to get more universal buy-in.

(Gwendal Roué) #112

+1 for everything, and I don't really care about configuration.

What I care about is the quality of the automatic reformatting. And by quality, I very specifically mean its ability at digesting a wildly wide range of inputs without turning them into a bloodshed of poor indentation, line breaks, or punctuation choices.

I want the tool to support me, not me to support the tool. I don't want to have to split an expression into five ad-hoc variables just to avoid a ridiculous or ugly output. I'm already busy enough.

I can and will follow community-blessed good practices, but I don't want practices that the tool has not learned yet to be deemed bad by default. I want the tool to respect code it does not understand.

Such level of quality can not be achieved in a single stroke. I thus expect the tool to frequently iterate and improve, because the wild community of developers will always invent new fancy ways to write Swift code.

I foresee and hope an ever-growing list of unit and regression tests.

I finally hope that it will be possible to upgrade the tool independently of Xcode, in order to profit from the most recent improvements.

(Michael Ilseman) #113

@allevato, since you introduced the word "official", and that seems to be a huge point of contention, could you define it or elaborate a bit more on what that means? Is it possible to draw an analogy to the messaging and intent of the API Design Guidelines?

For example, is it fair to say something like: to be idiomatic Swift, you should follow the naming rules API Design Guidelines and the code formatting rules Style Guidelines?

(Charlie Fish) #114

I think Swift should be careful not to enforce certain conventions in terms of styling. Code styling is always a personal thing. I think it would be hard to create an "official" style guide since it will be a high point of contention in the Swift community.

That being said I think having certain recommendations and even an optional formatter to enforce those recommendations could be a really great thing. I think there is a huge difference between "Official Style Guide" and "Recommended Style Guide". Although I think a "Official Style Guide" would be a really bad thing, I think a "Recommended Style Guide" could truly benefit the Swift community.

(Frederick Kellison-Linn) #115

@allevato has made clear that true "enforcement," in the sense that improperly formatted code would not compile, is not really on the table. Any provided formatter would be optional, and would be "official" in the sense that it is the canonical formatter adopted and maintained by the Swift project. Given this, would you support calling such a feature the "Official Style Guide," or would you prefer that, even if the feature set was identical, that this be branded as a "Recommended Style Guide"?

(Charlie Fish) #116

Based on what you said I think "Recommended Style Guide" more accurately describes what it truly is.

(David) #117

recommended is too strong. I think default perfectly captures the intention here. Swift doesn't recommend anything. It provides sensible defaults. People recommend things.

(Frederick Kellison-Linn) #118

Sure, but Swift is run by people, and the Swift project does have a voice of its own, whether you view that as the voice of the community as a whole or of the Core Team. I think the already-mentioned API Design Guidelines are a perfect example of recommendations from Swift. They’re stated with pretty strong language—almost everything is an imperative, rather than a suggestion or recommendation—and every Swift codebase I’ve seen follows these guidelines quite closely. I think having an analogous Style Guidelines document falls into the same sort of realm, with the added benefit that it is easier to enforce automatically.

(^) #119

My belief is any style guide should focus on high-level things like when to use optionals, when to use throwing functions, usage of “with” closure blocks, when to use guards vs ifs, etc.

I do not think anything productive will come of trying to enforce trivial formatting things like brace placement or indentation. Everyone will disagree on this, and i would not like to be told where to put the opening { on a line.


Should there be an official style? Only if there is great formatter tooling to help enforce it
Should there be an official formatting tool that enforces this style? Only if there is an official style

I'm with some other people on here that if we have an "official" formatter, that we don't make it configurable. The main thing i want from it is settling formatting debates so those conversations don't happen and everything is consistent.