Pitch: an Official Style Guide and Formatter for Swift

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

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.

8 Likes

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.

1 Like

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.

10 Likes

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

1 Like

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".

6 Likes

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.

3 Likes

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?!

4 Likes

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.

1 Like

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.

2 Likes

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.

7 Likes

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?

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

1 Like

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.

1 Like

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.
19 Likes

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."

5 Likes

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.

2 Likes

At this point, we're intentionally not discussing specific style guidelines—merely whether any should exist. It's too soon to assume that any syntactic constructs would have a particular formatting applied to them because nothing has been ratified. It sounds like you're assuming that acceptance of this proposal would "lock in" certain existing style decisions?

i’m assuming so, otherwise what would such a stylebook even be based off of?

From the pitch:

We intend for there to be an opportunity to discuss the specifics of what would be in the style guide.

2 Likes