Pitch: an Official Style Guide and Formatter for Swift

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
  • Should Swift have an official, recommended style :

I would have said absolutely yes if it had shipped with Swift 1. But now I feel like the ship has sailed and you’re gonna have a hard reformatting entire codebases.

I also feel like the majority of people saying yes here will have a hard time accepting whatever is proposed when it doesn’t match their style.

  • Should Swift have a built-in formatter:

Even without an official style we should have a formatter that doesn’t require to install third party dependencies and comes by default with SPM and Xcode. (I know Xcode is not discussed here but I would hope that if this is accepted Apple could implement it in Xcode no more than one year later). I don’t like to waste compile time formatting but I want it tot be integrated on the editor magically, and that’s the only current way of doing it until Xcode does it properly.

That said, if Xcode offered a better plugin system and third party tools could be integrated properly, I’m not sure there would be any point on having and official formatter.

  • Should the official Swift style be the only support style.

No, no way. Although is true that supporting more styles highly reduces the utility of an official styleguide, as I said on point 1, I don’t think you’re gonna convince everybody to use 100% of the style guide. So an ability to tweak it is necessary, is better to follow 99% of the guide and using official tools instead of following 0% and relying on other tools.

  • What tool should become the official?

Now that’s a harder question to answer.

The proposed tool seems to have the biggest chance as, as the pitch says, it has been thought to be integrated with swift since the begging. That said unless it becomes fully customizable and extensible I don’t think it should be the official one.

I’m really fond of swiftformat and I’ve been using it since it was released. It has helped to avoid discussions and it’s blazing fast and customisable, two required characteristics for any formatter.

And finally, as Nick as mentioned, a Swift formatter kind of needs to have semantic knowledge of the code, so I expect an official tool to be able to do that, specially if integrated with the compiler.

4 Likes

Could you post the argument?

There are two places where self is required when referencing a member:

  1. when member name is shadowed by local variable/argument
  2. when self is captured in a closure

Otherwise it's redundant.

2 Likes

I would rather discuss particular style issues in separate threads? If this becomes the thread about all style issues then the discussion is doomed.

elm-format and gofmt were mentioned several times in this thread. I have created a poll in Elm’s discussion forum so that we could get a better idea how having an “official” style guide and a formatter works for them. If someone can do the same for gofmt, I think it would be an interesting data point, too.

(I understand both Elm and Go are much simpler languages than Swift and writing a high-quality automatic source code formatter is hard as it is, so we can take this with a grain of salt.)

16 Likes

Ha, I was notified that a similar question was already asked in the State of Elm 2018 survey with these results:

I think that’s fairly convincing. (To add a personal note, I write very little Elm and the formatting makes me roll my eyes because of things like leading commas and too much whitespace, but I also came to like it, a kind of Stockholm syndrome situation I guess.)

Again, I don’t know how much of this can be extrapolated to Swift, but I think we should give it some thought.

8 Likes

I'm afraid of starting discussions around the style guide itself, but I must admit I'm a strong proponent of Xcode's current swift case formatting because it mirrors the indentation of equivalent if statements instead of introducing two indentations levels:

switch e {
case .a:
    print "a"
case .b:
    print "b"
default:
    print "default"
}

if e == .a {
    print "a"
} else if e == .b {
    print "b"
} else {
    print "default"
}
11 Likes

The argument was made, reviewed, and rejected for Swift in SE-0009. It is not necessary to revisit that discussion here.

5 Likes

big fan of a configuration-less tool like gofmt, it’s amazing for productivity. if one is developed, would love to see it integrated with tools like swift-pm so it can be easily used as part of the development workflow

8 Likes

... and here it's getting interesting: Imho anyone should assume that the hypothetical official style breaks drastically with all personal preferences and make his decision under this premise. If I learned anything here, then it's that you'll always find someone with a contrary opinion.

11 Likes

well, guess i’m not voting for this proposal! how about we don’t make the style guide enforce divisive opinions like brace placement.

1 Like

As has already been mentioned, let's please not derail this discussion with arguments about specific syntactic constructs. We specifically posed this pitch as an existential question only in order to gauge the community's thoughts on the overall topic without tying it to a particular set of line items that would branch out into N different simultaneous debates.

5 Likes

Ok everyone. Lets vote on whether to have a styleguide that will be enforced by a no choices autoconfigure tool. Then in step2 its party time when everyone learns what aspects of the style guide he/she totally hates. and will not accept under any circumstances. At this point grab some popcorn and enjoy the show : )

5 Likes

IMO if you cannot support an official style guide irrespective of what specific style choices it makes, you should not support an official style guide. I fully agree with @Tino that your support for the consistency and conformity should outweigh any of your personal style preferences. If people advocate for an official style guide on the tacit assumption that they will be able to convince others to match their preferences, it may appear that there is a critical mass of support which totally breaks down when it comes time for specific decisions.

That said, “I support an official style guide as long as it is a style I like” is a valid position to take, but if your support hinges on the specifics of the adopted style, that should be made clear in discussion.

12 Likes

I'm all for Swift having a built in formatting tool and style guide. Even using the default configuration of SwiftFormat has made things a lot easier, and the settings I wasn't a fan of I quickly got used to. I noticed that I picked up the style after a few days and now format code as I write it (mostly) in the same style.

What are the strengths of the new tool - swift-formats approach compared to SwiftFormat and SwiftLint? I looked through the configuration options of the proposed swift-format tool and they look pretty basic when compared to what is offered by the existing community tools.

I'm confused why the community tools weren't considered to be merged instead? Is there something about their approach that makes them not ideal?

I just don't want to end up with a rushed formatting tool that doesn't handle code correctly. I have issues where Xcode doesn't indent correctly:

  private lazy var someView: SomeView = { [unowned self] in
    let v = SomeView()
    v.translatesAutoresizingMaskIntoConstraints = false
    v.someProperty = self.someProperty
    return v
    }()
5 Likes

Hi Tony,

FWIW, my 2c is a strong yes that the Swift project should have preferred style guide, and we should integrate it by default with the tooling. This opinion is based on long-term envy of the Go community having a standardized style, and seeing the positive efforts, and personal experience having recently started a project that uses gates commits on having clang-format pass. Having this tooling really does simplify a ton of things. Of course, if we go this way, it shouldn't be required that code follow the style guide, we should just make it the easiest path for the community to do so.

That said, my opinion is that the efficacy of this for the community will depend a lot on the actual details of the style guide, and it will be difficult to get convergence on one true style. Given the inevitable controversy around the discussion itself, it might make sense to do a proposal between this one and the concrete proposal, where you lay down a set of guidelines that will eventually shape the detailed rules - something akin to the API design guide.

Taking a three step approach in the proposal cycle a) this proposal, "should we even have it", b) a "lets agree on the goals of what style is about" and c) here are the mechanical details and a tool that enforces them, could help turn some of the heat from the discussion into a more positive discussion about values, goals, and their tradeoffs.

To be concrete, instead of starting with, should we put braces like:

if x {
}
if x 
{
}

We talk about the important of vertical whitespace, code density, how much code fits in a given screen, etc.

-Chris

19 Likes

Tony, please interpret feedback like this as signal from the pitch phase that you should incorporate into the proposal to make the actual review more productive. If someone is confused about this, then it is best to clarify this in the proposal itself, e.g. at the very beginning with a bulleted lists of FAQs.

-Chris

4 Likes

Absolutely—I have a number of clarifications staged locally that (I hope) will make the proposal less open to misinterpretation. Just waiting for the dust to settle at this point so I don't miss anything :slightly_smiling_face:

2 Likes

awesome, great work Tony!

1 Like