Chapter 49: Scala Best Practices (CB-800 to CB-805)

The CB-800 series detects Scala-specific defect patterns that apply to any Scala project. These checks are motivated by the language’s dual nature: Scala supports both object-oriented and functional paradigms, but idiomatic Scala strongly favors immutability, expression-oriented control flow, and the Option type over null. The CB-800 series enforces these conventions by detecting mutable collections in production code, null literals, wildcard imports, explicit return statements, var declarations, and blocking calls inside Future blocks. The checks are grounded in the Scala style guide, Scalastyle, WartRemover, and Odersky et al. (2004).

Overview

# Run all compliance checks including CB-800 series
pmat comply check

# Example output:
# ⚠ CB-800: Scala Best Practices (CB-800 to CB-805): [Advisory] 0 errors, 12 warnings, 4 info:
# CB-800: Mutable collection `mutable.HashMap` — prefer immutable collections (src/main/scala/Service.scala:34)
# CB-801: Null literal — use Option[T] instead (src/main/scala/Repository.scala:19)
# CB-804: `var` declaration — prefer `val` for immutability (src/main/scala/Cache.scala:11)
# CB-805: Blocking call `Thread.sleep` inside Future — use non-blocking alternative (src/main/scala/Worker.scala:45)
# CB-802: Wildcard import — import specific members (src/main/scala/Api.scala:3)
# CB-803: Explicit `return` — anti-idiomatic in Scala (src/main/scala/Parser.scala:67)

The CB-800 series is advisory — it reports with Warn status but does not block CI or commits. Violations are categorized into three severity tiers:

Defect Taxonomy

Immutability (CB-800, CB-804)

Safety (CB-801, CB-805)

Style (CB-802, CB-803)

Detection Algorithms

CB-800: Mutable Collection Usage

Detects usage of scala.collection.mutable types in production code. Mutable collections break referential transparency and make concurrent code unsafe without external synchronization. Import lines are excluded — the check targets instantiation and type annotations:

// ❌ Mutable collections in production (CB-800 Warning):
class UserCache {
  private val users = mutable.HashMap[String, User]()
  private val pending = mutable.ArrayBuffer[Request]()
  private val queue = mutable.Queue[Task]()
}

// ✅ Immutable alternatives:
class UserCache {
  private val users: Map[String, User] = Map.empty
  private val pending: Vector[Request] = Vector.empty
  private val queue: Queue[Task] = Queue.empty
}

Detected types: mutable.Map, mutable.Set, mutable.Buffer, mutable.ListBuffer, mutable.ArrayBuffer, mutable.HashMap, mutable.HashSet, mutable.LinkedHashMap, mutable.LinkedHashSet, mutable.Queue, mutable.Stack, mutable.TreeMap, mutable.TreeSet.

CB-801: Null Usage

Detects null literals in Scala code. Null references are the source of NullPointerException at runtime and defeat the type system’s ability to track absence. Scala’s Option[T] type provides a safe, composable alternative:

// ❌ Null usage (CB-801 Warning):
def findUser(id: String): User = {
  val user = db.lookup(id)
  if (user == null) throw new NotFoundException(id)
  user
}

var connection: Connection = null  // deferred initialization

// ✅ Option-based alternative:
def findUser(id: String): Option[User] =
  db.lookup(id)

var connection: Option[Connection] = None  // explicit absence

The detector performs word-boundary matching to avoid false positives on identifiers like nullable or nullify. Lines containing Java interop annotations (@Nullable, @javax, @java, JNI) are excluded:

// ✅ Not flagged (Java interop):
@Nullable
def getHeader(name: String): String = headers.get(name).orNull

def fromJava(@Nullable value: String): Option[String] =
  Option(value)

CB-802: Wildcard Import

Detects wildcard imports (import pkg._ in Scala 2, import pkg.* in Scala 3) that pull an entire package namespace into scope. Wildcard imports cause ambiguity when multiple packages export the same name, make refactoring harder, and obscure dependencies:

// ❌ Wildcard imports (CB-802 Info):
import com.company.models._
import org.json4s._
import akka.actor._

// ✅ Explicit imports:
import com.company.models.{User, Account, Transaction}
import org.json4s.{JValue, JObject, JArray}
import akka.actor.{Actor, ActorRef, Props}

Standard library wildcards are allowed by default because they are universally understood and unlikely to cause ambiguity:

// ✅ Not flagged (standard library):
import scala.collection.immutable._
import scala.concurrent._
import scala.util._
import java.util._

CB-803: Return Statement

Detects explicit return keyword usage. In Scala, the last expression in a block is its return value. The return keyword is a non-local return that interacts poorly with lambdas, for-comprehensions, and higher-order functions — it throws a NonLocalReturnControl exception under the hood:

// ❌ Explicit return (CB-803 Info):
def max(a: Int, b: Int): Int = {
  if (a > b) return a
  return b
}

def findFirst(xs: List[Int], pred: Int => Boolean): Option[Int] = {
  for (x <- xs) {
    if (pred(x)) return Some(x)  // throws NonLocalReturnControl!
  }
  None
}

// ✅ Expression-oriented:
def max(a: Int, b: Int): Int =
  if (a > b) a else b

def findFirst(xs: List[Int], pred: Int => Boolean): Option[Int] =
  xs.find(pred)

The detector uses word-boundary matching and a string-literal heuristic to avoid flagging return inside quoted strings.

CB-804: Var Declaration

Detects var keyword usage, which creates mutable bindings. Mutable variables make reasoning about program state harder, especially in concurrent code. Scala’s val keyword creates immutable bindings that support referential transparency:

// ❌ Var declarations (CB-804 Warning):
var count = 0
var name = "unknown"
private var cache: Map[String, Entry] = Map.empty

class Counter {
  var value = 0
  def increment(): Unit = { value += 1 }
}

// ✅ Immutable alternatives:
val count = 0
val name = "unknown"
private val cache: Map[String, Entry] = Map.empty

// For stateful computation, use functional patterns:
case class Counter(value: Int) {
  def increment: Counter = copy(value = value + 1)
}

// Or use Ref/AtomicReference for concurrency:
val counter = new AtomicInteger(0)
counter.incrementAndGet()

The detector catches bare var declarations as well as modified forms: private var, protected var, override var, and lazy var.

CB-805: Blocking in Future

Detects blocking operations inside Future blocks. Blocking calls occupy a thread from the execution context’s thread pool, which can lead to thread starvation and deadlocks. This is the most common cause of production Future-based systems becoming unresponsive:

// ❌ Blocking inside Future (CB-805 Warning):
import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

Future {
  Thread.sleep(5000)                          // blocks thread pool thread
  val result = Await.result(otherFuture, 10.seconds)  // nested blocking
  heavyComputation()
}

Future {
  synchronized {                              // contention on thread pool
    sharedState.update(newValue)
  }
}

// ✅ Non-blocking alternatives:
import akka.pattern.after

for {
  _      <- after(5.seconds, scheduler)(Future.successful(()))
  result <- otherFuture
  output <- Future(heavyComputation())
} yield output

// For shared state, use concurrent data structures:
import java.util.concurrent.atomic.AtomicReference
val state = new AtomicReference(initialValue)
Future {
  state.updateAndGet(_ => newValue)
}

The detector tracks Future { and Future.apply { block boundaries using brace depth counting. It flags any of these blocking patterns inside the tracked block: Thread.sleep, Await.result, Await.ready, .wait(), synchronized.

Test Code Exclusion

All CB-800 checks exclude test code using two mechanisms:

1. Test file exclusion: Files with stems ending in Test, Spec, or Suite, or starting with Test, or under test/, tests/, it/, spec/ directories
2. Production line filtering: Comment stripping via compute_scala_production_lines() — removes // line comments and /* */ block comments

This prevents false positives from test code where mutable state, null usage, and blocking calls are often acceptable for test setup and assertions.

Remediation Priority

When pmat comply check reports CB-800 violations, fix them in this priority order:

1. CB-805 — blocking in Future causes thread starvation and production deadlocks
2. CB-801 — null usage causes NullPointerException at runtime
3. CB-804 — var declarations create mutable state that is hard to reason about
4. CB-800 — mutable collections break concurrent safety guarantees
5. CB-802 — wildcard imports cause ambiguity during refactoring
6. CB-803 — explicit return breaks lambda composition

CI/CD Integration

# .github/workflows/scala-best-practices.yml
name: Scala Best Practices
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install PMAT
        run: cargo install pmat
      - name: Check Scala Best Practices
        run: |
          OUTPUT=$(pmat comply check 2>&1)
          echo "$OUTPUT"
          # Fail on Error-severity violations
          if echo "$OUTPUT" | grep -q "CB-800.*errors: [1-9]"; then
            echo "::error::CB-800 series has Error-severity violations"
            exit 1
          fi

Academic Foundations

The CB-800 checks are grounded in empirical research on Scala defect patterns and functional programming principles:

Specification Reference

Full detection logic: src/cli/handlers/comply_cb_detect/scala_best_practices.rs Aggregate check: src/cli/handlers/comply_handlers/check_handlers.rs (check_scala_best_practices)