Pitch: an Official Style Guide and Formatter for Swift

(Tony Allevato) #30

This is exactly the case that swift-format's respectsExistingLineBreaks configuration setting handles. If that setting is false, the formatter will aggressively try to fit blocks that can fit onto one line onto one line. If the setting is true, then we give the user more flexibility to add their own discretionary line breaks where it improves readability for them, as long as those line breaks don't create some other violation of the (yet-to-be-ratified) style.

Part of this whole process will be determining from the community exactly which knobs they think are valuable, so this is the kind of feedback we're looking for.

6 Likes
(Dave DeLong) #31

(This is a separate reply because it's a separate thought)

If we allow for overridable style guides, let's please learn from LLDB's mistake* and allow ourselves to have per-folder, per-project, and per-user styles.

For example, in a project, the formatter should consult, in order:

  • a style file placed in the same folder as the file being stylized. This allows for the case when you have a large monorepo, and different teams work in different sub-folders
  • a style file placed in the root of the project. This allows for a per-project style guide. For example, a contracting agency might have specific style requirements they're supposed to follow for a particular project
  • a style placed in the user's home folder. This allows for a solo developer to define a single ~/.swiftstyle.fmt (or whatever) file that captures his or her unique style, thus saving him/her from having to re-define it everywhere
  • the final, system fallback style defined by the compiler/SDK

*LLDB's mistake is that you can't have per-project .lldbinit files, which means you can't ship debugging tools that are unique to a particular project. This is a long-standing open issue with LLDB and frankly I'm pretty amazed it's never been addressed.

16 Likes
(Tony Allevato) #32

swift-format can do this today (see the Configuration section of the readme). It scans the directory containing the source file first, then upward through parent directories until it finds one, or doesn't and falls back to a default config.

Tweaking that logic to include other search heuristics, like user home directory, would certainly be a reasonable thing to consider.

6 Likes
(Adrian Zubarev) #33

I second this. There is a lot good feedback already in this thread. I would like to add that it would be amazing if we could have a project style and a local style. By that I mean that the IDE should format the code with your local style when viewed but save everything in the project style. So if you'd open the swift file in a text editor it will present the code in the project style, while the IDE will display a different formatting style with your local preferences.


And whatever the result will look like, please make any tooling that originated from this thread written in Swift and extensible, so more community members that are most familiar with Swift than other languages can contribute better. ;)

8 Likes
(Tony Allevato) #34

This idea is mentioned in "Alternatives Considered" above, but my view is that it's beyond the scope of what even can be proposed for the Swift project, because it relies on either specific IDEs
or source control systems to implement what you describe.

Nothing about what we're intending to propose would preclude someone from using a workflow like this, but it's not something that the Swift project can provide in isolation.

5 Likes
(Argyrios Kyrtzidis) #35

To clarify, this was trying out swift-4.2-branch version which only supported invoking swiftc for parsing. There's a faster way in swift-5.0-branch by calling into sourcekitd, and swift-5.1-branch is even much faster due to changes I first outlined here.

4 Likes
(Boris Triebel) #36

For: Powerful and configurable and convenient to use formatting tools.
Against: A single blessed style to rule them all.

9 Likes
(Shai Mishali) #37

That's awesome news! Thanks!

(Diogo Tridapalli) #38

Dave's comment expressed exacly what I think.

8 Likes
(Pedro José Pereira Vieito) #39

Exactly!

Yes, I think it is very important for the Swift community to have a standard style and the tooling required to enforce and define it.

(Adrian Zubarev) #40

Maybe I'm just thinking out loud, but if the tooling we are talking about is potentially fast enough restructuring a single or multiple files that are tokenized, wouldn't it be just a consequence of this whole project? I mean even if it was a CLI you'd execute a configuration to format cached code with local style and when saving you can pick the project style. The tooling itself does not require IDE support, it just needs to be designed so it can quickly reformat the code with a different style when requested.

To be clear, it's not a dealbreaker for me, but something along the lines would be awesome.

(Lily Vulcano) #41

My few cents:

Code style serves many masters. Part of the code's intent is clarity for the person who is writing it; part of the intent is clarity for the people who will read it in the future; part of it is mechanical (e.g. matching indentation style so others don't have problems); and part is purely an expression of shared aesthetic values.

Often, strict compliance to a set of rules makes it harder to achieve some of these goals. I have idiosyncratic formatting in several places, allowing the small deviation from the norm to serve the goal of clarity while at the same time having a consistent style where these issues do not matter.

So:

+1 at having a style guide that makes recommendations.

+1 at having tools that make it the default to apply these recommendations. For example: a guide that shall serve as a style guide for Xcode completions, the formatting of Swift fixits as they are presented in error messages or applied in Xcode, served via LSP as suggestions etc.

A mild rebuke at requiring strict, 100% adherence to a maximalist style that doesn't allow local clarity deviations.

±0 to requiring strict, 100% adherence to a well-thought-out set of principles that doesn't hinder the above.

15 Likes
#42

543919427‰ YES
I love the experience of writing rust code, tapping ctrl+s and my code being prettified automatically. Not having to debate internally about where to split the line is nice.

Having official style guide would also be great. I don't feel strongly about most of the formatting decisions, but I love consistency.

Oh, and -1 for forcing people to use the official style. It doesn't sound nice.

5 Likes
(Marcin Krzyzanowski) #43

Take Python. Maybe we should discuss language gramma change instead, so it allows "a single approved style" only - problem solved?

(Andrew Madsen) #44

I couldn't agree with Dave more. Make swift-format part of Swift? Yes, let's do. Come up with an official style guide and make it the default? Sure. Enforce that style? No x 1million.

10 Likes
(Tony Allevato) #45

Just to make sure we're not getting hung up on terminology, the term "enforce" in my mind means that the formatter, when run on the code, would transform it into whatever style is ratified as the official style. (And one of our open questions is whether that is one single style or whether it can be configured, and if so, to what degree.)

It sounds like some other folks might be interpreting "enforce" as "code that does not conform to the style is invalid" in the sense that the compiler wouldn't accept it. That's not what we're proposing—it's certainly a position that one could take, but I'm fairly certain it would be a non-starter.

There is nothing being suggested that would prevent anyone from just not running the formatter ever on their code. That's their prerogative.

13 Likes
(Frederick Kellison-Linn) #46

I support a recommended style guide for Swift, and the inclusion of a swift-format tool.

If swift-format is performant enough, I think it would also be interesting to consider allowing for on-the-fly formatting via some specification that could, e.g., allow Xcode to support different viewing and saving styles, so that users could write and view code using whatever style they want, but the project would have one consistent style when viewed “raw.”

3 Likes
(Patrick Balestra) #47

I am very happy to see this being talked about. I would be very much in favour of having a single tool that is able to format Swift code, and I feel like it shouldn't be integrated only with Xcode. I know people who use VS Code to write most of their Swift tools (I do that myself from time to time), so seeing that this project is starting out in the open is already a good step.

I also feel like if we get the Swift team to care about these tools, their quality will definitely increase. I've found a couple of bugs in the third-party solutions that are powered by SourceKit under the hood, and that's because SourceKit wasn't meant to be used in that way and the maintainers are not really checking their API changes against these tools. Using SwiftSyntax and including the tools required in the Swift project, would definitely raise the quality of the tooling in my opinion.

I spent the last couple of weeks formalising our internal Swift style guide, and trying to get most projects to adopt it. It has been difficult, and this would have been much easier if the tools were included in the IDE (or available as plugins for the most popular ones).

I think it's pretty much agreed that including a formatter in the Swift project is a good idea and I honestly would love to see this pitch move forward to its full extent: enforce the code style everywhere. Sure, people will dislike it at first, but looking at the big picture I think the time gained from formatting code manually (or with tools, those still takes times to install and integrate) is something that we should strive for. On the other side, it's also true that tools should help developers, and we don't want people to waste time in fighting the formatter all the time.

I am definitely +1 this pitch, and happy to help contribute where I can.

6 Likes
(Ankit Aggarwal) #48

Here is a trivial SwiftPM integration if anyone wants to try the swift-format tool with their Swift package.

12 Likes
(Thomas Krajacic) #49

@Aciid you are fantastic! Thank you!

1 Like