Pitch: an Official Style Guide and Formatter for Swift

Should there be a recommended style? Yes
Should there be an official formatting tool that enforces this style? Yes
Should that official formatting tool be configurable? Not sure

With the proviso that such a recommended style must be sufficiently nuanced and sophisticated. For example there might be exceptions to the 'one true brace' style after a multi-clause boolean expression or function signature that spans more than one line.

Should there be a recommended style? Yes
Should there be an official formatting tool that enforces this style? Yes
Should that official formatting tool be configurable? No
Should the official formatting tool be optional? Yes

My concern is that configuration flexibility will result in fragmented styles. When you then attempt to leverage code that conforms to a different style, you're no farther ahead. That said, I know I haven't used languages that enforce styling, and I'm concerned that many of us expressing opinions haven't spent significant time in languages where code-style-enforcement is accepted.

So I asked a friend who has been learning Swift and has significant experience with code-style-enforcement. Here's what he had to say, and I think it was well said.


In any language, there are stylistic opinions that can be backed up with heuristic measurements. Then there are things that are basically preference. The former are usually easy to get past, but the latter can be what creates unnecessary obstacles for teams.

If a team's preference is unified and consistent then there is no real issue. Otherwise, I've found it's better to enforce consistency and adopt the code's conventions than it is to frequently battle the overhead of mixed style. This overhead comes from reading, reviewing, OCD fixing, and discussing. This cost is compounded when adopting various open-source libraries or code from other parts of the organization.

When the language itself determines the preferences, everyone just gets used to it and formatting wars just...go away. It makes it much easier to adopt or contribute to other codebases.

Next, the language tooling can build enforcement into the build process. IDE's can auto-format and compilers can check format. So now nobody spends any time formatting code.

And what is best, nobody spends any time making or fixing picky formatting comments in code reviews.

This has been my biggest complaint about learning swift...every example I read uses different horizontal and vertical spacing preferences. When I borrow code from one project, I have to comb through it to adjust spacing or someone inevitably spends time having to ask me to correct it (and I'm just thinking, "...but I used an example we borrowed from this other project...").

...and then concurrently working on an Elixir project where a simple mix format formats all the code perfectly, the difference is very stark.


Yes, we need an official Swift style
Yes, there should be an official tool for applying formatting
No, the style shouldn't be configurable or you're no further ahead in terms of mixed styles between projects and dependencies.
Yes, when developing you should be able to ignore the styling (temporarily) and then apply the formatting once you're ready to clean things up.

5 Likes

Slightly confused by this. They mention above how nice it is to be able to run a command that formats all the code perfectly. This would still work even if the formatter was configurable. Wouldn't that solve the problem?

Formatting someone else's code according to my formatter configuration isn't a good use of anyone's time, particularly with respect to a code review, contributing back, etc.

Assuming there's a formatter config file in the project, the formatter would follow the project's formatting I assume?

Project A uses formatter config A
Project B uses formatter config B
Project A depends on Project B.

You're suggesting that when working on Project A (and therefore Project B as well), I'd end up seeing a mix of styles depending on which file I'm in? No thank you.

One true style. Then there are no (more) fights, no discrepancies, no opinions, no more time wasted on the trivialities.

Humans would adapt and this whole issue would go away.

But again, I've not spent significant time with go-fmt or mix format so I'm mostly echoing what I hear from peers who do.

4 Likes

In that case, I apologize for misreading the pitch so significantly.

I guess I interpreted this omission (combined with some of the other language) as implying non-configurability. This impression may have been strengthened by the posts expressing a desire to exclude configuration options. You may want to update the proposal further to be more clear about this.

IMHO, this meta-topic is really better suited to a preliminary discussion and not an actual SE proposal. I don't think it's fair to ask people to review a meta-proposal without knowing what the concrete style guidelines and formatting tool will look like in practice. The consensus in this thread is that most of use would like to see something, but there is a broad range of opinions about what that should be. We can't effectively evaluate a proposal without knowing what the details look like. There is a reason proposal require a concrete solution with a detailed design (and an implementation since Swift 4).

If we can reach a clearly dominant consensus in the community on some minor style issues, especially "micro-style" questions like colon hugging, I think it would be reasonable to omit configurability in those areas. That said, it's not clear to me where a clearly dominant consensus exists and where it doesn't. We would need to have discussions in each area to find out and I don't think we should push non-configurable style decisions where a clearly dominant consensus does not exist.

When it comes to larger style questions (such as where to put line breaks and how to perform indentation) I think there will reasonably be a wide range of opinions. I don't think it would be wise to try to push non-configurable style rules in these areas.

4 Likes

This is true for new users, but there are (a lot of?) people who have already developed such preferences. Shipping a non-configurable tool might exclude them from using it even if they might mostly agree with other choices.

3 Likes

What happens when you start a new job and they don't use line breaks in your preferred way? Does it impact your development and happiness in a significant way?

4 Likes

agree. there are so many good, higher level patterns in Swift that ought to be promoted by such a tool. It makes no sense politically, or technically for it to bog itself down in those stylistic debates (“sPaCE aFTeR cOLOnSsSS!1!1!1??”) which matter the least but incite the most visceral reaction.

4 Likes

For what it's worth, treating this as a meta-proposal was the direction we were given by @tkremenek after a discussion with the Core Team. (Not trying to pass the buck here; just explaining the reasoning for why it's been presented the way that it has and that it's a decision that was carefully considered.)

The intention here was to determine, before contributing any specific guidelines or work to the Swift project, whether the community would be strongly in favor of or opposed to the idea in general. We did anticipate that some readers may not wish to answer the existential question without knowing precisely what those details would be. Ultimately though, given the subjective and spirited views on code style, we felt it was important to gauge the community's general mood separate from a discussion of concrete style guidelines in case the discussion around the existential question provided any useful data to motivate how we present any potential guidelines.

1 Like

I think discussion of this in general is perfectly appropriate. It just doesn’t make sense to me to do a formal review of a proposal that is void of the details necessary to meaningfully evaluate it. That said, it’s obviously not up to me and it makes sense that you would follow direction they gave you.

Whether something is "clearly dominant" can be determined empirically. It doesn't require debate, nor is debate even a good way to gauge such a thing.

(But much code is private, you might say--to which I say, (a) I'm not convinced that style breaks down along these lines; (b) since it's code invisible to the community, it needn't necessarily be weighed in matters of style, since in many ways style must be seen.)

1 Like

I have no objection to anyone attempting to perform an empirical analysis. That would be quite useful. But the method and results should be shared for community discussion, don’t you agree?

I would support the development of code style guidelines and a tool that automatically applies them.

In terms of achieving the four numbered goals from the proposal, a formatter with opinionated default but that is also configurable seems to achieve almost all of them, except perhaps the “mental load” half of point 2. I don't find the feedback from users of languages with unconfigurable formatters to be that persuasive, because (as far as I know) these languages didn't start out having configurable formatters and subsequently remove all configuration, so they don't really have the experience required to support a preference here. If the defaults are at all reasonable then it seems likely that the “power of defaults” will make the default style very widespread even if the formatter is configurable.

2 Likes

as someone who uses a minority colon format (let a:T) and strongly believes people should space their colons however they want, I strongly recommend that a style guide deal with issues like

// `enumerated()` is a poor way of iterating through indices, 
// recommend `zip(values.indices, values)` instead
//   ~~~~~                         ~~~~~~~v~~~~~~~~~~~
for (index, value):(Int, Float) in values.enumerated() 
{
    ...
}

instead of

// y no colen spaCE ?
//  ~~~~v~~
let foo:Int = 13

There are good reasons to prefer zip(values.indices, values) over values.enumerated(), which are not widely known, and deserve the spotlight that an “official” style guide would give. There is no good reason to prefer let foo: Int over let foo:Int other than pure imperialism. trying to enforce a style on something like that is just being petty for no gain.

1 Like

except for all of the listed motivations in the pitch?

1 Like

this is a bit of circular reasoning. a code base isn’t going to run any faster, play nicer with gyb, be easier to refactor, or be less prone to bugs if you change the colon spacing, and if your code review is getting held up by the :s, i’d consider that a reviewer problem. every day on here I read and comment on other people’s code which uses different colon and brace spacing than i do. i never have a problem with it, it doesn’t slow me down, and i have never started a fight over it. Most of the motivations in this pitch sound to me like people problems, not colon problems.

2 Likes

Should there be a recommended style? Yes
Should there be an official formatting tool that enforces this style? Yes
Should that official formatting tool be configurable? Yes, to the smallest extent required to achieve agreement
Should the official formatting tool be optional? Yes

I, too, am envious of Go’s formatting capabilities, and would love to see something similar both built into the Swift toolchain and accessible from Xcode and other IDEs.

I support creating such a tool, with minimum comfigurability. I think that some level of per-project configuration may be unavoidable (see the near-infinite mentions of line length in the previous posts), but the less variation between project styles, the better off we’ll be.

2 Likes

Exactly this. One thing to consider is that some individuals have visual impairments and need some extra spaces in the code they write to be able to visually parse it. If you make a strictly enforced style guide agreed upon by the majority then you will almost certainly leave those with accessibility challenges out in the cold suffering.

One guy I worked with needed the space after "(" and before ")" in order to be able to visually parse the code on screen, even with the best programming fonts and largest reasonable font size he could use.

So:

So, I'm in favor of having an auto-formatter. Just please make sure that I can tweak it and turn on or off things that I want.

What we want is readable code, and everyone tends to have slightly different definitions of what that means.

Agreed. A formatter that can take a simple rules file and apply those rules to code is the best solution. Include a "standard" rules file if you like. Organizations can then customize that rules file to accommodate the individuals on their hopefully diverse team.

3 Likes