Pitch: an Official Style Guide and Formatter for Swift

(Tony Allevato) #121

Absolutely. My intent with the word "official" is the definition "having the approval or authorization of an authority or public body". In this situation, "authority" == the Swift Core Team. That is simply meant to convey that the Swift team is giving that particular set of style guidelines their blessing as an example of what they think is optimally readable Swift code, is one which they would ideally adopt across the various Swift projects (corelibs and others), and which they would be happy with being the "default" style for an adopted formatting tool without any other configuration, since there must be some default behavior. Clearly these matters are subjective and pleasing everybody is a non-goal because it's impossible, but that doesn't mean we can't make any progress in the area.

The implication of the word "official" is that any other style guidelines outside of those would be "unofficial". That doesn't mean they're bad or incorrect, nor does it imply that attempts to use a different style would be met with enforcement or restriction of any kind. Perhaps there is a concern that anyone who wishes to use a different style than the hypothetical "official" one or presents such code in a forum would be met with derision? If that were the case, that would be a personal intolerance problem, not a style guide or tool problem, and it's something that should obviously not be allowed to happen. People should feel free to use whatever style they wish if they're not contributing to a project that has specific guidelines.

I'll make this more explicit in the proposal text before it goes to review since it's been a point of contention or confusion.

To some degree, yes. I do consider the comparison to the API Design Guidelines to be apt, because we're trying to achieve a similar goal on a different axis of the development workflow. The Swift project recommends API design guidelines that are "official" in the sense that they are blessed by the Swift team and hosted on swift.org, but they are not required to be followed nor does the compiler try to force users into them. In a personal project, people can design APIs however they wish, but in team environments or other collaborative situations, having a common agreed-upon set of guidelines improves communication and understanding. It also makes it easier to transition from project to project, if those other projects follow the same guidelines. In fact, if it were more tractable to create a tool that could apply grammatical analysis to APIs to an accurate enough degree that it could correctly diagnose and suggest corrections for names and signatures, I'd personally be very excited to have that and would embrace it.

The same argument can be made for code style. I'm not 100% sure "idiomatic" is the word I would use here because I think that holds more weight in the API Design Guidelines case than it does for code formatting, but I can't think of a better one off the top of my head. Regardless, the underlying motivations are the same: to smooth out and improve communication, optimize transferability of skills, reduce barriers to entry for newcomers, and remove less important issues from consideration so developers can focus on more productive matters.

Some community members have strong preferences about personal style, and that's fine. Nobody can, will, or should stop them from doing whatever they wish. But for the many above who have said they would embrace a unified set of guidelines that the Swift team feels capture the notion of "ideal Swift code, stylistically" and a tool to make applying that effortless, this work is for them. Developers naturally look to the language owners to provide guidance and best practices, and having guidelines that are blessed by the Swift team—especially if the core projects themselves adopt them—will be incredibly useful for communication and education.

(Andrew Bennett) #122

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

As long as “enforces” means that it automatically applies the style, and it is configurable from those defaults. IMO none of the existing public projects are mature enough to automatically apply their styles. IMO none of them have a good mechanism for extension, yet.

I think this proposal could start with less controversial changes and build on them:

  • A library to support formatting and linting
  • Support in SwiftPM for building plug-ins (there’s some duplicate symbol linking issues atm, SwiftLint is having this issue)
  • Runtime support in Swift for discovering plug-ins.
  • Nice-to-have: An extensible way to provide fix-its (I like that warning/error work from custom build scripts in Xcode, having a canonical text format for fix-its would be great)

At worst all of these would be useful to the community even if the rest of the proposal was rejected. If the proposal went ahead then the “official” tool and style would ideally be a minimal layer on top of the above things, other tools could also use it. This may end up enforcing an architecture on other tools, so the library would ideally be a collaboration like the Swift Server Working Group.

I’m interested to know if the focus on formatting would mean that 3rd party linting projects would lose steam. Does this proposal allow for lint-like validation as well? I think that could only be done via extensibility.

(James Berry) #123

I appreciate your thinking and explanation, @allevato. I still believe that calling it a "default style" rather than an "official style" is the correct choice. The nice thing is that default means "what you might use if you don't have a reason to use something else". Official, on the other hand, implies that it's the law, that it's the one true way, etc. Even though we wouldn't plan to "enforce" a particular style, having something called an "official" style means that many organizations will be apt to, perhaps without really considering the consequences. Some here will argue (and have) that would all be for the best. I can anticipate commit hooks rejecting commits that aren't formatted in the official style. For some projects that may be the right choice. But I'm concerned that calling something the "official" style makes it all the more likely that such choices would be made without sufficient thought, simply because, well, it's "official". By picking our nomenclature more carefully, we influence the perception: I believe "default" sets a better tone than "official".


Are there reasons you might use something else that aren't just preference?

(Tony Allevato) #125

I don't believe that follows from the definition I cited—approval of one thing does not imply disapproval or limitation of other things. If I were proposing a "required Swift style", then that would be a different story. I do feel that folks are reading too much into a single word, reflecting a fear of a malevolent dictator telling them their code is bad or wrong when there is none.

Making a decision without sufficient thought isn't something that a single word will change. More importantly, what is the concrete harm that would be done in this scenario? If the style that comes out of this process is reasonable to read or write and has been vetted by numerous Swift experts, I'm not sure why choosing to apply that style over potential others would be a bad thing. Indeed, many projects do have pre-commit hooks to reject commits that aren't formatted in that project's decided style, and in my opinion, those projects are better off for it. But despite that view, I neither wish to nor intend to force any particular style or workflow on anyone outside of my own projects.

(James Berry) #126

I think it would be wrong to suggest that being "just a preference" has little weight. Clearly that's the major thing here. The length of my hair, the manner of my speech, my choices in clothing or location, etc, may all be just preferences, but they define who I am and allow me to feel that I have some choices, and in doing so give me at least a sense of independence. Were I in the military and all of those things were dictated beyond choice, some things would be easier: I wouldn't have to choose my clothing or when to cut my hair, but I would have lost a sense of independence.

(^) #127

A lot of common “whitespace/indentation/newline/capitalization” swift conventions were inherited from common objective c conventions that may or may not have had a good reason. Others are just completely arbitrary and I can think of good reasons why the common style is “wrong”. (example: spaces after colons.) Others are just artifacts of tooling (switch case indentation, /// doc comments) that are inferior but still common because people don’t want to fight the IDE. It would be a shame if IDE bugs got codified into a style guide.

other “common practices” aren’t even common at all, by quirk of definition. An example is omitting self.. There’s a strong argument to be made for mandatory self., but because this advice isn’t universally followed, there’s a lot of Swift code which omits self, and because code that uses self is by definition a subset of code that optionally uses self, the “common practice” in the swift community is to make self optional.


What I'm getting at is that I don't see value in there being an "official" or "default" style guide if it isn't commonly followed. I don't understand the point if nothing is consistent across projects, and every organization has to still decide what rules they are enforcing. Having a 3rd party style guide would be great (and they exist), and having 3rd party formatters would be great (and they exist).

If there are reasons beyond that where making different stylistic choices is because of practicality in specific situations, that might change my opinion on whether a formatter should be configurable

(Tony Allevato) #129

A couple examples do come to mind:

  • You have a multi-language code base, like Objective-C and Swift, but your IDE only supports one global setting for line length and indentation size (like Xcode). In that case, if the two languages have different guidelines on those characteristics, editing your code can be a frustrating experience.

  • Similar to the case above, your code is sent to or rendered on systems other than your IDE, such as code review systems, where certain formatting settings might pose difficulties. For example, GitHub's side-by-side PR diff rendering doesn't handle wide lines very well unless you have an extremely wide browser window.

And possibly others. So there are practical reasons why there may need to be some level of choice, and I do think it's important to identify those as part of this process.

switch case indentation is not an IDE bug. If I remember the history correctly, it was inherited from the LLVM code base, and the reason it was done there is because switch blocks, unlike other curly brace blocks, do not introduce a new scope, so there was a semantic meaning behind that decision. Now to be fair, that meaning does not apply to Swift per se, and it's fair to debate whether or not the same decision should be made for Swift, but whether someone agrees or disagrees with it, let's make sure the origins aren't just brushed off as a "bug".

(James Berry) #130

Yes, it is just one word, but it implies a lot. Consider how many people have interpreted it in a way other than you intend it. My point is that the word suggests much that perhaps isn't intended by the definition you intend them to study. Consider words that are politically charged ("snowflake" or "MAGA", to point out just a few examples in current usage): a lot of power comes in the choice of a single word.

@Tony_Parker mentioned that he would be apt to use a different style for Foundation. He clearly might have good reasons for doing so, though perhaps solely preference. In any event he's in the group of those we would seem to encourage to make his own choices: he's thought it through and has good reasons for what he wants to do. But my point is that the fact that Foundation "doesn't follow the official style" could become prejudicial. And it if were a project of far less stature, it would become even more prejudicial. On the other hand, to say that "Foundation doesn't follow the default style" sounds to me much less judgemental, more that it has simply made a different choice.

I'll finish by repeating that I'm in favor of the overall concept. I really like the idea of a great well-written tool that is ubiquitous and that can support a default style as well as other styles. I like the idea of suggesting a style. It's just that I think the word official, even as just one word, sets the wrong tone.

(Boris Triebel) #131

I prefer "default" over "official". I suggest to avoid the term "enforce". A formatter obviously formats, calling formatting "enforcing" gives it the wrong connotation. Especially with some fans of copying the go concept of "enforcing" a single format upon all users of the language - which this proposal is not about, right?!

(Frederick Kellison-Linn) #132

What do you view as the difference between gofmt (and its associated style) and what's being proposed here? The Go compiler will happily compile code that has an improper format, and the use of gofmt is entirely optional. No users are forced into using the official Go style.

(Boris Triebel) #133

a) Having a powerful and configurable tool with options. b) Not having one style that is presented everywhere as the single correct way even if it does not work best for me with all that follows from it.

(Gwendal Roué) #134

Is the frequent comparison with gofmt honest? I mean, does Go have to deal with functions accepting multiple closures, or if/guard followed by multiple let/case/etc, or type/methods definitions enriched with multiple where clauses (to name a few formatting challenges that are uneasy even for humans gifted my many neurons)?

I'd like that more people acknowledge that formatting Swift is potentially much more difficult than formatting Go (reputed for its simplicity, quite unlike Swift). We face a fascinating but tough challenge. There lies a big difficulty, I think. I'd love to be wrong.

Disclaimer: I love SwiftLint as much as I hate it. //swiftlint:disable:some_rule is always right under my fingertips.

(Frederick Kellison-Linn) #135

How customizable this tool would be has been discussed heavily in this thread. There are a large number of proponents for a swift-format which accepts no configuration options, and many who would prefer that swift-format not even have a default, "unconfigured" behavior at all.

This, too, is up for discussion. @allevato presented his view of how an "official" style would be presented and communicated to Swift users just a few posts back.

FWIW, I think there would be markedly different levels of adoption if this were presented as a "suggested" style, the "default" style, the "official" style, or the "correct"/"proper" style, in increasing order of adoption. Granted, this is based on how compelled I personally would feel to follow style that went against my personal preference, and not based on empirical evidence. Are there any popular languages which have an officially endorsed style without providing any sort of tool to enforce that style?

(Boris Triebel) #136

Aehm. No need to explain how a discussion thread works ; )

(Frederick Kellison-Linn) #137

Sorry, I didn't mean for that to come across as flippant—I was just trying to answer your question:

with my understanding that such a decision is well within the scope of this proposal.

(Paul Cantrell) #138

It’s disingenuous to claim that an Apple+Google-authored, core-team-endorsed standard with the word “official” doesn’t come with some degree of coercion. You defend this proposal without being mindful of the power you wield, as if this were just another open source offering. It is not.

Yes, of course, other teams are not strictly forced to do anything. Heck, we aren’t forced to write Swift as it exists at all; we are all free to fork the compiler, aren’t we? But this isn’t about personal freedom. It’s about practical effects.

In practical terms, this is a proposal that has consequences that “just another style guide+formatter” would not. This proposal — intentionally or not — would shut down the extensive research @Erica_Sadun has done into the nuances of Swift style. It would shut down the work put into the (currently more mature) open source alternatives. I’m sure your own tool is excellent and written with great care, but brilliance and expertise are not a drop-in substitute for software maturity (cf SPM).

Like it or not, you are treading on prior art with giant feet. Tread carefully.

As you proceed, please, please acknowledge the power imbalance in your favor here, and use it carefully.

Nobody disagrees with this. At least not that I’ve seen on this thread.

The question is whether invoking the authority of the SE process is preferable to individual teams using their best judgement.

Several people have talked in this forum about “ending holy wars” over formatting. I shudder to think of working on a team where such minutiae dominate discussion. And I doubt whether any team that succumbs to that would do any better arguing over whether to deviate from an Official Style Guide in the places where that guide inevitably falls short. Because it will fall short — ask Erica about the nuanced alternatives she’s grappled with writing her book. When it does fall short, an ill-positioned official style guide only adds fuel to the argument. Yes, the single word “official” does make a difference, if not semantically then socially.

All this is why I suggest having a style guide that the Swift project itself uses for its own code, and leaving it at that. This has several advantages:

  • It still provides a reasonable starting place for other projects, a common point of reference.
  • Teams consumed by senseless style bickering who crave a single style guide can adopt that one and be done. (I remain skeptical that this truly fixes the underlying problems on such a team, but if it works, it works.) However…
  • By not assuming to speak for other projects, it does not trample the prior art in the same way. Yes, that’s a psychological and not a technical difference. Yes, it matters just the same.
  • Since it’s about the Swift language project itself, the style guide doesn’t have to go through the SE process, which is ill-suited for the hundred bikeshed-prone questions such a proposal would raise.

(Tony Allevato) #139

If the concern is primarily centered around the word "official", then perhaps we should draw from @Michael_Ilseman's comparison to the "API Design Guidelines" above and drop any qualifiers, calling them simply "Code Style Guidelines".

Then, one way I could suggest that they might be presented to developers would be to update the text on the swift.org Documentation page to say something to the effect of:

"These design guidelines and code style guidelines explain how to make sure that your code feels like a part of the larger Swift ecosystem."

(^) #140

if anything, that’s just another reason why the common switch case formatting shouldn’t be codified — it gives a wrong impression of the language semantics. Also, the thing with the /// comments is an IDE bug by any measure.