skip to content

In SwiftFormat, how do swiftformat:disable, :next and swiftformat:options comments keep a hand-aligned table of Swift constants from being reformatted?

level: middleimportance: should knowfreq 30%

answer

  1. a comment the formatter reads
  2. name the one rule that collapses spaces
  3. disable, then enable, around the block
  4. :next, :this and :previous need no enable
  5. enable only undoes an earlier disable

basics

~10 s

Wrap the table in // swiftformat:disable consecutiveSpaces and // swiftformat:enable consecutiveSpaces, or use // swiftformat:disable:next for one line. swiftformat:options changes option values for part of a file instead of switching rules off.

solid answer

~40 s

The rule that flattens a hand-aligned table is `consecutiveSpaces`, which collapses runs of spaces to one everywhere except at the start of a line and inside comments and strings. A `// swiftformat:disable consecutiveSpaces` comment turns it off until a matching `// swiftformat:enable consecutiveSpaces` or the end of the file, leaving every other rule running. For a single line, `// swiftformat:disable:next ruleName` covers the line below it, and since 0.57.0 `:this` and `:previous` cover the comment's own line and the one above; none of them needs an `enable`. `// swiftformat:options --indent 2` changes option values from that comment on, and `swiftformat:options:next` changes them for one line. `swiftformat:enable` only cancels an earlier `disable` in the same file; it cannot switch on a rule that was off when formatting started.

code

swift · 19 lines
swift
import Foundation

enum BreedSize {
    // swiftformat:disable consecutiveSpaces
    static let toyMaxKg      = 4.0
    static let smallMaxKg    = 10.0
    static let mediumMaxKg   = 25.0
    static let largeMaxKg    = 45.0
    // swiftformat:enable consecutiveSpaces
}

struct Shelter {
    let name: String

    func label() -> String {
        // swiftformat:disable:next redundantSelf
        "Shelter: \(self.name)"
    }
}

go deeper

for a junior

Recall that a // swiftformat:disable comment turns named rules off until a matching enable, and that disable:next covers just the following line.

for a middle

Explain which rule collapses aligned spaces, how :next, :this and :previous differ, and why swiftformat:enable cannot turn on a rule that was never enabled.

for a senior

Disable the narrowest rule instead of all, use swiftformat:options when a setting rather than a rule is wrong, and move repeated exceptions into .swiftformat with --filter or --exclude.

for a principal

Set a team norm for when an exception lives at the call site and when it belongs in shared configuration, so directives stay rare and reviewable.

## Why the table gets flattened Teams often align a block of constants by hand so the values read as a column: ```swift enum BreedSize { static let toyMaxKg = 4.0 static let smallMaxKg = 10.0 static let mediumMaxKg = 25.0 } ``` SwiftFormat's default-enabled `consecutiveSpaces` rule replaces any run of spaces with a single space, except at the start of a line (indentation) and inside comments or string literals. On the next run the column disappears. The fix is not to exclude the whole file, which would switch off every rule for it, but to tell SwiftFormat about that one block. ## Directive comments SwiftFormat treats any `//` or `/* */` comment containing `swiftformat:` as a directive. The rule names are SwiftFormat's own camelCase identifiers, separated by spaces or commas. | Directive | Scope | Needs an `enable`? | |---|---|---| | `// swiftformat:disable rule1 rule2` | from here to a matching `enable` or end of file | yes, to end early | | `// swiftformat:enable rule1` | cancels an earlier `disable` | no | | `// swiftformat:disable:next rule` | the line below the comment | no | | `// swiftformat:disable:this rule` | the comment's own line, as a trailing comment | no | | `// swiftformat:disable:previous rule` | the line above the comment | no | | `// swiftformat:disable all` | every rule, until `swiftformat:enable all` | yes | `:this` and `:previous` arrived in SwiftFormat 0.57.0; `:next` is older. ## Two rules the directives obey 1. **`enable` only undoes a `disable`.** It cannot turn on a rule that was not enabled when formatting started, so `// swiftformat:enable isEmpty` in one file does nothing if the project never enabled the opt-in `isEmpty` rule. 2. **An unknown directive is an error.** A comment such as `// swiftformat:ignore next line` does not match `disable`, `enable`, `options` or `sort`, so SwiftFormat reports an unknown directive with its line number and does not format that file. Name the narrowest rule that does the damage. `// swiftformat:disable all` around the table also stops indentation, trailing-space trimming and every other rule inside it, so the block slowly drifts out of step with the rest of the file. ## Changing options instead of rules Sometimes the rule is right and only one of its settings is wrong for a stretch of code. `swiftformat:options` takes the same option flags as the command line: - `// swiftformat:options --indent 2` applies from that comment onward in the file. - `// swiftformat:options:next --wrap-collections before-first` applies to the next line only, with `:this` and `:previous` working as they do for `disable`. An unknown option name in the directive is an error unless `--unknown-options` says otherwise. ## Related directives worth knowing - `// swiftformat:sort` above a declaration, or `swiftformat:sort:begin` and `swiftformat:sort:end` around a run of declarations, has the `sortDeclarations` rule sort them by name; since 0.64.0 the directive also sorts array and dictionary literals. - SwiftLint's own comments, such as `// swiftlint:disable:next trailing_comma`, are a different tool's syntax and do nothing to SwiftFormat. A line both tools must leave alone needs one directive from each. ## Choosing between a directive and configuration Directives are for exceptions a reader should see next to the code. When the same exception repeats across many files, it belongs in `.swiftformat` instead, as a `--disable`, an option, or a `--filter` section scoped to matching paths. A useful review rule: - one aligned table or one generated block → a directive at the site - a whole folder of generated sources → `--exclude` for that folder - a style the team rejects everywhere → `--disable` in the shared file Keep the directive next to a short comment saying why, so the next person does not delete it as noise. ## Traps in review - `:next` means the next **physical** line. A directive followed by a blank line, or by another comment, covers that line and not the code beneath it, so keep it directly above the code. - `:this` belongs at the end of the line it protects, as a trailing comment. - A range `disable` with no `enable` lasts to the end of the file, quietly exempting everything after the table. - Swift code blocks in Markdown files, formatted with `--markdown-files`, use a different mechanism: `swift no-format` or a `<!-- no-format -->` comment skips a block, and options can follow the fence, such as `swift --indent 2`.

  • Why not wrap the table in // swiftformat:disable all instead of naming consecutiveSpaces?
    `all` switches off every rule in that range, including indentation and trailing-space trimming, so the block stops tracking the rest of the file and can hide real mistakes. Naming `consecutiveSpaces` keeps everything else running and tells a reviewer exactly what the exception is for.
  • A teammate writes // swiftformat:enable markTypes to get MARK comments in one file; why does nothing happen?
    `markTypes` is an opt-in rule, and `swiftformat:enable` only cancels an earlier `swiftformat:disable` in the same file; it cannot enable a rule that was off when formatting started. The rule has to be enabled in `.swiftformat` with `--enable markTypes`, scoped with a `--filter` section if it should apply only to some files.

  • swiftformat:enable can switch on an opt-in rule for one block of code.
  • A swiftformat:disable:next comment must be closed by a matching enable.
  • SwiftFormat honours swiftlint:disable comments that name the same style.
  • The only way to keep an aligned table is to exclude the whole file.
  • SwiftFormat silently ignores a misspelled swiftformat: directive.

Assumes SwiftFormat 0.64.0; the :this and :previous directive modifiers were added in 0.57.0, and 0.64.0 extended swiftformat:sort to array and dictionary literals.