Pitch: an Official Style Guide and Formatter for Swift


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


#120

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.


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


#124

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.


#128

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?