Pitch: an Official Style Guide and Formatter for Swift

Evolution Pitches
81

I am strongly in the camp that says we should improve the official tooling in this area, but that we should not have an “official style”. I really like this suggestion by @Tony_Parker that this tooling should be oriented towards supporting style decisions made by each team using Swift.

I think it would be fine to have a default configuration of this tooling aligned with a default style. But I agree with @Paul_Cantrell that there is a very important distinction between a default style and an “official” or “recommended” style. I’m sure that even if my preferred style were adopted as the “official” style, before long I would regret having rigidly committed to adopting that style forever.

I would like to hear more specific concerns about the impact on automated code transformations mentioned which was mentioned by @Joe_Groff. That said, my instinct is that I wouldn’t necessarily expect these tools to apply the precise style I intend and would be willing to re-apply my style afterwards if necessary. I can’t imagine it would be worse than some of the behavior Xcode exhibits today.

8 Likes
82

+1 Official Style Guide
+1 Official Style Formatter
+1 Option to define custom styling rules to be enforced by the formatter

83

Can you elaborate on why that is? I'm interested in hearing these points of view because my position is traditionally the opposite: "I don't care what the style guidelines are as long as they're within reason, the important thing is I don't have to think about them anymore either when writing or reviewing code." I'm more interested in having a common or official style for the educational and logistical aspects, not necessarily for advocating for a particular style at the expense of others.

There are certain knobs that I think need to exist for practical reasons (for example, being able to adjust column limit is important when code is written or viewed in multiple tools that may not all handle wrapping the same way), but for other things like whether line breaks are preferred before or after operators, I code in various languages with slightly different guidelines and I don't end up opinionated about them because I just let the formatter take care of it for me. It only becomes something I care about if I'm involved in actually deciding the rules, in which case I'll naturally make the case for my preference, but I won't oppose or regret reasonable alternatives if the consensus ends up being something different.

9 Likes
84

A single, official style would be really great - until you discover the first choice in it that you consider to be utterly terrible.
It's not realistic that everyone or even just a majority agrees on a single set of rules, so whatever you choose, many people will be disappointed.
I think this will be true no matter how strict the enforcement is: As soon as there is an official style, anyone who disagrees with it will be constantly exposed to backlash, and I'd rather prefer that backlash coming from a tool like gofmt than from other developers; I don't think that having a "recommended" style is a good idea at all.

I'm not sure how many options are truly polarizing, but if it's just tabs vs spaces, having this as a single degree of freedom might give us most benefits of uniformity without repelling a large group of users.

3 Likes
85

+1000 this will make my life as an open source maintainer so much easier.

6 Likes
86

My take on it is to have the editor auto-detect a file’s existing formatting when it gets opened, convert it to the user’s preferred style for editing, and convert it back when it’s time to save. That way everyone gets to see the files however they want to see them. Even if two people on the same team and working on the same file disagree. There’s no reason I can think of (besides tradition) that this needs to be any more complicated for the user than changing fonts.

Editors could even be a “on-disk format” setting in their project files, so that the on-disk representation is consistent across all the files.

3 Likes
87

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

Using gofmt is such an unbelievably liberating experience: never worry about trivial style details again. If the official tool supported a some limited configuration that might be nice as long as it didn't cause reduced performance or reliability, but I'd rather have a completely unconfigurable official formatter than no formatter at all as long as the results were relatively sane.

3 Likes
88

Exactly this

2 Likes
89

And then we end up with Xcode templates that look like this (excerpts from the SpriteKit Game template):

    private var label : SKLabelNode?
    CGSize.init(width: w, height: w)
    func touchMoved(toPoint pos : CGPoint) {

There should be some basic rules for formatting. I'm not saying that every single detail of formatting should be defined, but some of the basics - yes. For example, unifying the spaces around :, etc.

The column width, whether to use spaces or tabs, that's up to the project. But some basics should be defined and enforced IMHO.

5 Likes
90

I also fear a problem similar to that of Swift Package Manager, where Apple putting its name to an official (but low-priority, minimum-viable) tool will convince everyone that the existing, mature and feature-rich community tools are effectively dead and no longer worth supporting.

This would be highly detrimental, but one could say that an almost trillion dollar company could put more weight (money where its mouth is) and increase theirs tools and software development spending. Ok big can of worms opened... closing it.

Instead of building a new formatting tool, I would prefer to see Apple adding better hooks into Xcode to support 3rd party formatting and linting tools seamlessly, and the energy of the Swift open source community directed towards improving the open source tools we already have.

+1 standardise better hooks and libraries support that any tool can use. Allow a fair game, see LSP development, and let your community decide too.

91

Properly configured, you can get a combination of swiftlint and swiftformatter working like a treat and that is without further progress in the official tooling, like SourceKit (and SourceKitten ;)), and Xcode hooks that could further help there.

Let’s also not forget the integration of those tools with CI solutions and integration with pull requests on services like GitHub with an industry wide accepted tool like Danger.

There is a LOT of preparatory work that can enable any formatter to do its job and lots of functional and non functional requirements like those that I do not see even roughly drafted there. It feels like debating whether we should develop a Language Server Protocol support or just further a single monolithic integration (Xcode).

I would like the solution to receive full Apple involvement in development and maintenance (more than SPM) and similar community involvement and commitment. I am glad people in Google are finding it useful for the time they use Swift, but there needs to be wider commitment as well as acceptance.

92

I learned Swift as my first programming language and really wish I had had a styleguide or even better an auto-format button in Xcode. I think it would be a huge help for newcomers.

6 Likes
93

Like others, I agree that gofmt is a great success story and I would really like to have an oficial Swift style guide.

Unfortunately I don't think this will work with Swift. Go was able to do this because it is a very opinionated language and they did this from the beginning, without leaving it to a forum to decide the details. The existence and the details of the style was decided by the core developers.

Swift on the other hand is consensus oriented and I don't think it is realistic to expect to ever reach consensus on this topic. Many people feel that they have "unique needs" and these needs are conflicting with each other. And nobody here has the gravitas to put their foot down and make such a controversial decision.

5 Likes
94

Should the Swift language adopt an official style guide and formatting tool?

I would like a style guide to exist and a formatter that renders it. Would I personally follow it? Probably not as I am unlikely to agree with everything it stipulated. I would hope the formatting tool would allow for configuration (and the current Google tool already does so to some degree), but even if it didn't, I could just ignore it. I don't expect advanced code migrations and transformations to be compatible with any arbitrary style. If I go out on my own, the language shouldn't stop me, but I accept that some theoretical future tooling may be incompatible*. That's fine. That's the status quo today when there's no style guide at all. If configuration/customisation of the formatter was possible, I'd certainly embrace the tool, if not the default style set.

Why am I in favour even if I am so ready to ignore it? Because newcomers to the language often want strict direction, I did when I first started. Having this documentation and foundation is important. Down the road, individuals build confidence and can make their own choices if they want to. For teams and companies, a Swift.org style guide would offer a baseline that they can accept it as is, or build upon.

In the same way that source control systems provides templates for contributor guidelines, code of conduct, etcetera, just because many people tweak the templates or go their own path doesn't make having them a pointless endeavour. A style guide is just another resource of documentation really, and that has to be beneficial. If there are willing humans ready to drive this through, who aren't already tied up with other parts of the Swift project, which it seems like there are, I'm all for it.

(*EG: I would expect Apple/Swift sample code and documentation to consistently follow the Swift.org style guide, which is perfectly reasonable whether you are someone adhering to the guidelines or not.)

4 Likes
95

Being a teacher, this gets a big +1 from me.

I spend a lot of time trying (and failing) to teach new students proper formatting habits. I'm not talking about enforcing a single style here, just trying to get them to write code that is readable and follows common conventions is hard enough.

An official style and a tool that reports violations would be a big help for me.

6 Likes
96

I'm strongly in favour of having the Swift language adopt an official style guide and formatting tool. I also thinking that the swift-format developed at Google is a very good starting point: it is very close to the formatting I've seen in the wild and in the Standard Library. Count me in.

2 Likes
97

I'm 100% for it.
Whether people will use it in their own projects or not is really up to them. I hope that in time they will. However, for official projects and for those who want contribute to them it's extremely important that we arrive at one Official Style Guide.

98

This is a valid concern, but I would hope that the Core Team would take a firm stance to avoid bike-shedding here.

One thing we should not do is choose the style of the standard library. That is quite unusual and not representative of Swift code in general. If the style of the standard library was picked I believe the formatter would not see wide adoption.

99

Should the Swift language adopt an official style guide

yes

and formatting tool?

yes

I don't even need it to be extensible, but it matters where you set the boundaries.

When you add rules to formatter:

  • first comes quantifiable readability
  • then diff-merge-ability

After that you are left with opinions, and historical baggage.

Consider short guard statements:

// 1.
guard let foo = some() else {
    return nil
}

// 2.
guard let foo = some()
    else { return nil }

// 3.
guard let foo = some() else { return nil }

// 4.
guard let foo = some()
else {
    return nil
}

// 5.
guard let foo = some()
else { return nil }

// 6.
guard let foo = some()
    else {
        return nil
    }

Should there be only one way to write it?
Two ways?
Should it be the same for long and for short guard statements?
Or we can leave some slack here, but set strict boundaries?

Either do not add a rule, when there are no strong arguments, or make it configurable.

1 Like
100

Should there be an official style? I don't care.
Should there be an official formatting tool that enforces this style? I don't care.

All I care about is that if there is an official style and formatting tool, it must not be configurable at all. Either we should do go-fmt, or nothing: I see minimal value in having an official tool with configuration. Once we require configuration, just let people use whatever tool they want: it's just another configuration setting, essentially.

28 Likes