SE-0250: Swift Code Style Guidelines and Formatter

I like the distinction @lorentey drew between a linter and a formatter:

I would argue that enforcing explicit self is not something that should be in the scope of this formatter. Such things are the concern of a linter.

8 Likes

I see, thanks for the clarification.

1 Like

...uh... I suspect that is not what you meant...

The Chicago Manual of Style directly competes with New Hart’s Rules (a.k.a. “Oxford style”), The Associated Press Stylebook, the U.S. Government Publishing Office Style Manual, The Canadian Style, the AMA Manual of Style, the Interinstitutional Style Guide of the EU, the Australian Manual of Scientific Style and dozens of others which all disagree with one another willy‐nilly.

That is precisely the situation we have in Swift right now and is the perceived problem it seems the proposal authors wish to resolve. I understand the proposal more as a request for a single, centralized style guide, more comparable to the guidelines of the AsociaciĂłn de Academias de la Lengua Española, the Rat fĂŒr deutsche Rechtschreibung or the Académie française which are each the singular highest authority on style in their respective languages, though all of them explicitly call out specific endorsed variations for particular settings (regions, disciplines or circumstances), clearly describing when and where said variation is and is not helpful. Since everyone is familiar with the standard, a particular publication or institution can efficiently describe its style by simply saying, “We do x, y and z our own way.” and everyone implicitly knows that a through w should all be done the standard way. It is far more efficient because there is much less to read and learn when switching to a new setting. It also has the effect that any deviation has a good reason instead of merely being the accidental result of unquestioned habits.

(Amusingly, I suspect this proposal would be far less controversial if it and the surrounding discussion were in any language besides English.)

I think the guidelines could probably include a lot of conditional recommendations. “Unnamed closure parameters are generally preferred when a, but named parameters tend to be better when b, c or d.” The formatter does not have to enforce every guideline; it can refrain from dealing with ones that require human interpretation or contextual information to get right consistently.

8 Likes

The approach you describe here sounds quite reasonable to me. I really feel like those advocating a no configuration tool and a universal style are trying to take the substance out of style. Why should style in programming be simpler than it is for natural language? Why should professional programmers think less about style than professional writers of natural language do?

6 Likes

By coincidence, I've been thinking recently about comparison with natural language as well:
Wouldn't it be great if all people all over the world would speak a common language?
You could communicate with myriads of humans without barriers, you wouldn't need translation for books or movies - and ultimately, it could even lead to peace on earth.
That looks like a goal that's much more laudable than easier accommodation with other peoples code, and I doubt anyone with a sane mind could question the positive aspects.
Still, we have hundreds of languages, and any serious attempt to change this would probably produce nothing but big grieve, because most people would welcome such a lingua franca - but only if it's their native tongue that's chosen.

In this aspect, SE-0250 is written quite clever, as it avoids controversy, so that anyone can project that it will be their favorite style that will finally be ratified...

1 Like

The road to hell is paved with good intentions... for me, wishes are not nearly as important as the actual outcome.
Nobody can precisely predict what that will be, but I thing you are stirring hopes that simply can't be fulfilled:

So how would this work? Will people who disagree with the official style not be allowed to start projects anymore, so that those who don't care are protected from alien style?

There's only one thing I know for sure: This debate already burnt a lot of hours, and I predict if it is really planned to discuss all decisions that are part of a complete styleguide here, the number of wasted man-months would be large enough to build several decent formatters instead — without the bureaucratic overhead that is needed for proposals.

3 Likes

I think that analogy is amiss. Different publishing styles are mutually intelligible, but different human languages are not†. In a similar way, different coding styles are interoperable, but differing computing languages are not†. The comparison you make is more at the level of the discussion over in this thread:


†for the most part

2 Likes

In reality, there is no such thing as an optional governance directive. If the benefits were perceived to be negligible, people wouldn't bother. On the other hand, if the benefits are non-negligible, the entire body of users will eventually converge towards it. There is no stable in-between state.

There will necessarily be pushback against projects that don't conform to the official style if there is one. You gave one reason yourself when you said that you find it easier to use and contribute to projects that conform to the same style: you said that you would prefer to contribute to projects that use it.

In fact, there are already style police patrolling GitHub projects in languages that don't even have an official style (examples 1, 2 from one of my more popular projects).

I think that there is broad consensus that having code formatters is a good thing. As I said earlier, I would support a proposal that integrates formatters with SwiftPM/IDEs in some way, and I would either support or not care about an initiative that proposes a style for projects started by the official Swift body.

However, that style is not credibly optional if it's called "official", or if the tool that enforces it is the only one that offers seamless integration. To me, that's an important distinction.

7 Likes

No, an analogy might be between different regional accents (northern/western US vs southern US for example), which are just as culturally sensitive and fraught with identity as differences in language. tino’s point stands.

^ for a swift community example, i have had people complain about capitalization of sources/ of all things. if you can’t tell that sources/ is the folder that contains the sources in an SPM project, you really need to get checked

I was originally in favor of this at the pitch stage, but now after reading all the comments I’ve changed my mind.

This. It has been brought up multiple times in both threads that having style discussions on SE will be a never ending battle. Just looking at how many messages both of these threads have, we could predict that the style debates will go on forever.

I also completely agree that the tool should come after the style. Since this is a meta-proposal which proposes to have a style and a tool, it’s very inappropriate to include adoption of a concrete tool in this proposal.

I would rather have the Core Team put forward a styling guideline. Let the community look up to that guideline, same way as everyone unquestionably looks up to Swift API Design Guidelines today.

9 Likes

I don't see how that conclusion follows at all, and respectfully, the suggestion that "people [...] will not be allowed to start projects" is unproductive hyperbole. Rather, let's presume that we adopt a formatting tool that allows some degree X of configuration. The situation is this:

  • People are welcome to do whatever they want on their own projects. They may choose to adopt a set of recommended style guidelines, or configure the tooling to do something else, or choose not to use it entirely if it's not suitable for their needs.

  • If a project stores its configuration in its repository, then new contributors don't have to worry about learning in advance a new style or having reviewers come back with a large number of style-based comments. The tool takes care of it for them, and both users are more productive as a result.

If the style configuration can be saved in the project and automatically applied by a tool easily usable by anyone contributing to that project, then I don't care what the chosen style of that project is. I have no reason to care.

If people push back negatively against projects for no reason other than that they don't use a particular recommended set of style guidelines, then that's a social problem, not a tooling problem. I would personally find behavior like that incredibly toxic, and I sincerely hope that we can make decisions without the implied assumption that such toxic behavior would be predominant and unmanageable.

1 Like

The Swift API Design Guidelines went through Swift Evolution. In fact, it was the major item accomplished on Swift Evolution for Swift 3.

6 Likes

I have not enough expertise regarding the importance of American dialects, but I wouldn't expect that a unification would have the big effects I described ;-)
But certainly, life would be easy for many kids who learn English as second language if there wouldn't be several variants...

1 Like

For what it's worth, since it's been mentioned a couple times, I can provide a bit of context here. The choice to propose the tool first was deliberate, because the goal was to let the community easily explore proposed style guidelines on their codebases (for example, as new style guidelines would be proposed, they could be implemented as PRs, distributed as alternative builds, or some other mechanism). Since swift-format is specifically staffed for this purpose, we're able to guarantee that we can provide that experience for users. From my own experience, a style guide developed without the tooling to test it out on large projects is a style guide that often ends up with missed cases or assumptions that don't always hold up in complicated cases.

I think it's perfectly understandable that some may disagree with that approach, but I wanted to explain why that path was chosen.

9 Likes

I’ve missed that, thank you for pointing out! Maybe something can be learned then from those times? Before I go back to dig into the mailing list, I would assume those discussions took quite some effort?

FWIW "sources" only works on a case-insensitive file system. Personally, I think it would be reasonable for SwiftPM to add "sources" to the list of supported paths, but today it does not.

1 Like

Your explanation makes a lot of sense!

FWIW, I feel like most of those who care about consistent code style and maintain a large codebase already have some third party formatter set up on their projects.

So as much as I would personally like to see an officially supported tool, I don’t think it necessarily has to hold back style discussions from moving forward.

That's likely true, but that's also where the part about swift-format being specifically staffed comes in. We wanted to provide a better follow-up to any impending "here are some proposed style guidelines" than an implied "you're on your own to figure out whether the tooling you already use supports them and to modify that tooling to try it out". By having the tool first, it puts the responsibility squarely on us—where it should be, if we're proposing style guidelines—to provide a great experience for users to try them out effectively.