skip to content

In SwiftLint, how do swiftlint:disable:next, :this and :previous comments scope a suppression, and what goes wrong with a bare swiftlint:disable?

level: middleimportance: should knowfreq 58%

answer

  1. a comment command per rule identifier
  2. one-line modifiers next, this, previous
  3. bare disable runs to the file's end
  4. a default rule flags open-ended disables
  5. a stale disable is itself a violation

basics

~20 s

A swiftlint:disable comment with :next, :this or :previous suppresses the named rules on exactly one line: the following line, the comment's own line, or the line before. A bare swiftlint:disable stays in force until a matching enable or the end of the file.

solid answer

~40 s

The command is `// swiftlint:disable:<modifier> <rule> [<rule>...]`. `:next` covers the line after the comment, `:this` the line the comment sits on, `:previous` the line before; SwiftLint disables the rules for that line and re-enables them at its end. Without a modifier, `// swiftlint:disable force_cast` lasts until `// swiftlint:enable force_cast` or the end of the file, so later force casts slip through too. Two default rules police this: `blanket_disable_command` warns about a disable left open, and `superfluous_disable_command` flags a disable that suppresses nothing, such as one left behind after the code was fixed. Text after ` - ` documents the reason, and `all` disables every rule.

code

swift · 22 lines
swift
import Foundation

struct ClaimPayload {
    let raw: Any

    func amount() -> Int {
        // swiftlint:disable:next force_cast - the server contract guarantees an Int here
        let cents = raw as! Int
        return cents / 100
    }

    func legacyAmount() -> Int {
        let value = raw as! NSNumber // swiftlint:disable:this force_cast
        return value.intValue
    }

    func reviewedAmount() -> Int {
        let value = raw as! Int
        // swiftlint:disable:previous force_cast
        return value
    }
}

go deeper

for a junior

Recall the three one-line modifiers and which line each covers, and that the rule identifier goes after the command.

for a middle

Explain that a bare disable runs to a matching enable or the file's end, and what blanket_disable_command and superfluous_disable_command each report.

for a senior

Diagnose a suppression that does not work because the violation is reported on another line, or a stale comment flagged after a refactor, and fix it at the right line.

for a principal

Decide whether the team requires a ' - reason' on every disable and keeps both meta rules at error severity, trading friction for suppressions that stay honest.

## The command grammar SwiftLint reads **commands** from ordinary Swift comments. The shape is: `// swiftlint:<action>[:<modifier>] <rule1> [<rule2> ...] [ - explanation]` - The **action** is `disable` or `enable`. - The optional **modifier** is `previous`, `this` or `next`. - The rule list holds one or more rule identifiers exactly as SwiftLint names them (`force_cast`, `line_length`, the identifier of one of your regex rules), or the keyword `all`. - Anything after the ` - ` delimiter is a free-text explanation that SwiftLint ignores when it parses the rule list. Teams use it to record why the suppression is acceptable, so a reviewer reading the diff sees the reason next to the exception. Several identifiers can share one command: `// swiftlint:disable:next force_cast force_try` covers both rules on the next line, and each identifier is tracked separately, so disabling one rule never hides a violation of another on the same line. The rule identifier must match. A misspelled identifier suppresses nothing, and SwiftLint reports it as not a valid SwiftLint rule. ## How the one-line modifiers scope a region SwiftLint turns a modified command into a pair of commands: disable at the target line and re-enable at the end of that same line. The target line is fixed by the modifier: | Modifier | Line covered | Typical placement | |---|---|---| | `:next` | the line after the comment | a comment line above the statement | | `:this` | the comment's own line | a trailing comment on the statement | | `:previous` | the line before the comment | a comment line below the statement | Because the region is one line, it covers only violations that SwiftLint *reports* on that line. A rule that reports a long multi-line call at a different line from the one you marked is not suppressed, and the fix is to move the comment to the reported line, not to widen the disable. In the claims app, a payload parser that relies on a server contract might read: ```swift // swiftlint:disable:next force_cast - the server contract guarantees an Int here let cents = raw as! Int let value = raw as! NSNumber // swiftlint:disable:this force_cast ``` Both commands also work with `enable`, so `// swiftlint:enable:next line_length` re-enables a rule for one line inside a larger disabled region. ## What a bare disable does Without a modifier, `// swiftlint:disable force_unwrapping` opens a region that lasts **until a matching `// swiftlint:enable force_unwrapping` or the end of the file**. The usual failure is a disable added for one legitimate line and never closed: every force unwrap written later in that file, months later and by someone else, is silently accepted. `// swiftlint:disable all` does the same for every rule. SwiftLint ships a default rule against exactly this: 1. `blanket_disable_command` warns when a `disable` is not scoped with `next`, `this` or `previous` and not re-enabled, when a rule is disabled twice, when an `enable` has no matching `disable`, and on `// swiftlint:disable all`. 2. Its `allowed_rules` option lists rules where a whole-file disable is expected; the default list is `file_header`, `file_length`, `file_name`, `file_name_no_space` and `single_test_class`. 3. To turn it off for one deliberate blanket disable, the rule's own rationale shows the stack: `// swiftlint:disable:next blanket_disable_command` above the `// swiftlint:disable` line. ## Stale suppressions Code changes under a suppression. `superfluous_disable_command`, also a default rule, reports a disable command when the disabled rule would not have triggered a violation in the disabled region. That catches: - a force cast that was refactored away while its `:next` comment stayed; - a comment naming the wrong rule, one that is enabled but does not fire there, so the actual violation is still reported and the comment is reported as well; - an identifier that does not exist, reported as "'<name>' is not a valid SwiftLint rule; remove it from the disable command". ## Custom rules and the boundaries of this tool Regex rules defined under `custom_rules` are suppressed by their own identifier (`// swiftlint:disable:next no_print`), and the identifier `custom_rules` itself disables every custom rule at once. Commands only affect SwiftLint: a `swiftformat:disable` comment is a different tool's syntax and SwiftLint ignores it. Whether a given suppression is *justified* is a review judgement that belongs with the general material on baselines and suppressions; the mechanics above are what SwiftLint does with it.

  • A swiftlint:disable:next force_cast comment sits above a line, yet SwiftLint now reports the comment itself. Why?
    That is `superfluous_disable_command`: the line below no longer violates `force_cast`, perhaps because the cast was refactored into `as?`, so the suppression does nothing. Delete the comment. The rule keeps suppressions from accumulating after the code they excused is gone.
  • When is a whole-file swiftlint:disable reasonable, and how do you keep blanket_disable_command quiet about it?
    For file-level rules such as `file_length` or `file_name`, where the violation concerns the whole file. Those identifiers are in `blanket_disable_command`'s default `allowed_rules`; for another rule, add it to that option in `.swiftlint.yml` or put `// swiftlint:disable:next blanket_disable_command` above the disable.

  • A swiftlint:disable comment only affects the next statement.
  • swiftlint:disable:next covers the whole following block.
  • Disable comments can never produce a violation of their own.
  • SwiftLint honours swiftformat:disable comments as well.
  • A misspelled rule identifier in a disable comment disables all rules.
  • Text after the rule list breaks the command.