Pitch: an Official Style Guide and Formatter for Swift

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

That's not a matter of style or formatting. It is a matter of correctness of code; enumerated() does not return indices.

...and therefore it is a matter of style and formatting. One of these is idiomatic, and the other is not; there is no reason not to standardize and thereby eliminate the matter altogether.

Yes, indeed, style and formatting are issues that people deal with. Most of the readers and writers of code are people, not colons.

8 Likes

Right, this is what a linter is for.

2 Likes

I have no problem using different conventions depending on the language I'm writing at the moment. For example, the Allman style prevails in the C# world. These conventions are a useful flag for me to adapt my thinking to a particular language.

As a result, I'm in favor of a style guide and formatter for Swift. Speaking only for myself, configurability isn't a concern--if the default style differs from the code I've written before, I'll update my personal style to match.

4 Likes

Your first example feels more like the realm of a linter. It would be awesome to have a officially supported linter :heart: but this is a different discussion. The formatter should only bother about whitespace characters and has value in its own right.

4 Likes

I find @xwu's point about keywords a very good one. What about the (imaginary) vocal minority that are using custom preprocessors in order to use fn instead of func? Is it pure imperialism that func has been set in stone and there is no configuration option to change it? I'm sure they have very good reasons to prefer fn over func.

3 Likes

well, i suspect a lot of people use them interchangeably given poor knowledge of Swift’s Sequence/Collection hierarchy, and when used on Arrays, they are interchangeable, so it is a matter of style in that context. Those of us who use generics prefer zip on indices for consistency between Array and ArraySlice, but ultimately that is a style preference, for Array loops, since the code is functionally identical. But this is all very specific and not really relevant to the thread so i’ll stop.

not to shade the effort here at all, but in the spirit of standardization, it’d be nice if we had the same enthusiasm for standardizing currency/textbook types like RGBA, Vector, Matrix, Quaternion, Queue, RBTree, etc. Who’s in? (on a different thread of course)

well, count me in for the linter effort <13

i honestly probably will not use this style guide or formatting tool, though i have no objection to it being organized here. I (like others) just ask that we call it the Default style guide and not the “Official style guide” to emphasize it as a starting point rather than a prescription.

I believe the formatting tool that comes with it should be customizable, but customizations should not be called ‘Default style’, in order to maintain the standardization and consistency (and thus the whole point) of the default style rules.

In other words, we should not have a default-style-formatter, but rather just a style-formatter that is capable of applying the --preset=default style, along with downloadable, team-defined, and user-defined presets. I suggest this only because I suspect much of the code implementing a default style formatter could also be repurposed to apply other styles, and offers a win-win between those who want to preserve the uniformity of the default style, and those who want to use their own presets.

this is a pretty out-there example. i don’t think anyone is going through the effort to preprocess fn to func just so they can spell function declarations differently. I only recently bothered with getting an automated gyb preprocessor up and running in one of my build systems. Varying colon styles on the other hand are very much a thing.

What I do not understand, and would love to see answered by someone in this camp, is why posters in favour of a configurable tool believe that there should be an official language formatter.

As far as I can see, the desire to make the linter configurable boils down to a sentiment of "I am in favour of automated style enforcement, so long as we enforce my style". And that's fine, I get it. But if you want that today you can already have it: there are many Swift style tools already in place, as well as the new one proposed here. This is already the status quo.

What no-one has clearly elucidated in my view is why it is useful to have an official tool that does not have opinions about what the code should look like. So my questions to anyone in favour of a configurable official tool is simple: what utility is provided by such a tool that is not provided by the open source ecosystem today?

22 Likes

To me having a pationate preference over func foo() vs fn foo() seems much more substantial than let x: Int vs let x:Int. Why having one not be configurable is ok, while for the other is a travesty?

because fn foo() has never compiled with swiftc, whereas let x:Int has always compiled with swiftc.

1 Like

So can I count on your support for my pitch to make func keyword configurable?

That would be absurd right? Why make people have to choose over 2 different styles?

If func and fn had been interchangable since, say, 3.0, then i would, but they’re not, so i won’t.

These people who look for an authoritarian single style should get together and create a tool and use it among themselves. Please stop your efforts to take away my freedom and force your opinions on me. Seriously. What is this discussion.

2 Likes

There is another way to look at those two opposed forces.

For each configuration option you add, you multiply the number of configurations the tool has to support. This combinatorial explosion makes the tool output less predictable, and the quality of the code it generates more difficult to assert, maintain, and preserve in the long run.

A sufficient amount of work could overcome those difficulties, of course. But we need some people to actually provide this work. This question is at the root of the configuration debate. It's still very abstract at this stage. It will become more precise sooner or later.

I'll personally push for the highest possible Quality. If configurability has to suffer on the way, I personally do not care. This is my point of view, I am able to defend it, and I am sure I will find support. And I do not have anything against configuration itself.

5 Likes

If this formatter turns out to be either intentionally crippled or seriously limited because of implementation complexities for which not enough effort can be mobilized (because of people who actively work against it because of their religious belief in mono culture code style) then this whole effort will be end up as a really sad story.