Suppressing rules

Sometimes you need to ignore the output from Scalafix.

For linters, and for linters only, an easy way to achieve that is to selectively ignore some diagnostics via lint.ignore. However, this toggle is global, which is rarely what is needed.

Scalafix provides two methods for suppressing rules in source code: annotations and comments.

• Annotations: great for disabling regions of code but some source code locations are impossible to annotate.
• Comments: great for targeting precise source code locations where annotations don't work.

Annotations

It's possible to suppress Scalafix with @SuppressWarnings annotations. The @SuppressWarnings annotation is supported by many different tools so it's recommended to prefix the suppression with scalafix:.

For example, imagine we have configured the DisableSyntax rule to report errors for the usage of null and asInstanceOf but we want to suppress those errors inside a particular getUser method

@SuppressWarnings(Array(
  "scalafix:DisableSyntax.null",
  "scalafix:DisableSyntax.asInstanceOf"
))
def getUser(name: String): User = {
  if (name != null) database.getUser(name)
  else defaultPerson.asInstanceOf[User]
}

The scalafix: prefix can be left out if desired. However, when the scalafix: prefix is included then you benefit from "unused suppression" warnings that Scalafix reports for suppressions that can be removed.

The @SuppressWarnings annotation is detected without compilation. Any annotation matching the syntax @SuppressWarnings(..) regardless if it's java.lang.SuppressWarnings or com.example.SuppressWarnings will will trigger the suppression mechanism. This is done in order to support @SuppressWarnings for syntactic rules like DisableSyntax.

Suppress all rules with "all"

A convenient way to disable all rules is to inform the standard keyword all in the annotation:

@SuppressWarnings(Array("all"))
def foo: Unit = {
    foo(null)
    1.asInstanceOf[String]
}

Comments

It's possible to suppress Scalafix diagnostics and rewrites with // scalafix:on/off/ok comments. Comments can target more source code precisely than annotations since annotations are limited to definitions like val and class. For example, comments can disable a group of methods or an entire source file.

There are two alternatives to suppress rules via comments: single expression using scalafix:ok and regions using the scalafix:off/scalafix:on toggles.

Suppress expressions with scalafix:ok

Use // scalafix:ok comments to suppress Scalafix for an entire expression. The scalafix:ok comment can appear after an expression like this

List(1, "") // scalafix:ok

The scalafix:ok comment can also appear before an expression like this

// scalafix:ok
List(1, "")

The benefit of scalafix:ok comments is that the suppression is automatically enabled only for the range of the expression. There is no need for a separate scalafix:off.

Suppress regions with scalafix:off and scalafix:on

Use // scalafix:off and // scalafix:on comments to suppress Scalafix over an arbitrary range of lines. This is the last resort when neither @SuppressWarnings annotations or scalafix:ok comments are sufficient.

A scalafix:off can optionally be matched with a scalafix:on comment to re-enable Scalafix

// scalafix:off
foo(null)
1.asInstanceOf[String]
// scalafix:on

A scalafix:off with no matching scalafix:on will suppress Scalafix for the rest of the source file.

Selectively suppress individual rules

Both scalafix:ok and scalafix:off can selectively disable a list of rules. You can provide the list of rules to be disabled separated by commas:

// scalafix:off DisableSyntax.null, Disable.asInstanceOf
foo(null)
1.asInstanceOf[String]
// scalafix:on

List(1, "") // scalafix:ok Disable.Any

Document reason for suppression

You can optionally include a description after a semicolon ; for why a suppression is needed. The description is only for informational purposes for the person reading the code and will be ignored by Scalafix:

var x: Int = 0 // scalafix:ok DisableSyntax.var; I need mutability

// scalafix:off; temporarily disabling all rules until the code below gets refactored

Unused suppression warnings

As code evolves, a scalafix:ok comment or @SuppressWarnings("scalafix:Rule") annotation may become outdated. Scalafix reports warnings when it encounters unused Scalafix suppressions, which you are safe to remove

project/Dependencies.scala:4:19: warning: Unused Scalafix suppression,
                                          this can be removed
[warn]   val x = List(1) // scalafix:ok
[warn]                   ^^^^^^^^^^^^^^

Overlapping annotations and comments

Suppression via comments and @SuppressWarnings can be combined in the same source file. Be mindful not to introduce overlaps between the two as it can cause confusion and counter-intuitive behavior. Scalafix handles overlaps by giving precedence to the @SuppressWarnings annotation:

@SuppressWarnings(Array("scalafix:DisableSyntax.null"))
def overlap(): Unit = {
  val a = null
  // scalafix:on DisableSyntax.null
  val b = null // rule is still disabled because the annotation takes precedence over the comment
}