Scala Coding Standards

Scala Coding Standards

A comprehensive collection of Scala coding standards and best practices. Designed for AI agents and LLMs to generate high-quality, idiomatic, and maintainable Scala code.

Categories

Null & Option Handling [CRITICAL]

Represent absence and expected failure explicitly with Option and Either — never null.

Effect Systems [HIGH]

Keep side effects wrapped in IO at the edges, and keep core logic pure and referentially transparent.

Anti-Patterns [HIGH]

Recognize and eliminate recurring Scala anti-patterns that erode type safety, totality, and encapsulation.

Concurrency [HIGH]

Coordinate shared state and background work safely with immutable data, IO, and structured scopes.

Error Handling [HIGH]

Model and propagate failures explicitly with Either, Try, and typed errors instead of throwing.

Immutability [HIGH]

Default to immutable data and val bindings, updating through copy instead of mutation.

Implicits & Givens [MEDIUM]

Use Scala 3's given/using and extension methods deliberately, without implicit-driven surprises.

API Design [MEDIUM]

Shape public constructors, traits, and types so they are hard to misuse.

Collections [MEDIUM]

Use Scala's immutable collection API idiomatically, without unnecessary materialization.

Pattern Matching [MEDIUM]

Match exhaustively and readably instead of chaining accessors or if/else.

For-Comprehensions [MEDIUM]

Use for-comprehensions to compose monadic operations readably, not reflexively.

Naming [LOW]

Follow Scala's naming conventions for values, types, and symbolic methods.

Scaladoc [LOW]

Document public API contracts precisely, without narrating the signature.

Quick Reference

Null & Option Handling

def findDiscount(code: String): Option[BigDecimal] =
  discounts.get(code)

val total = for
  discount <- findDiscount(code)
  price    <- findPrice(sku)
yield price - discount

Effect Systems

import cats.effect.IO

def logAndSave(order: Order): IO[Unit] =
  for
    _ <- IO.println(s"saving order ${order.id}") // describes the effect; nothing runs yet
    _ <- IO.delay(database.save(order))           // same — deferred until this IO is run
  yield ()

Anti-Patterns

import cats.effect.{IO, Ref}

def counter(): IO[Ref[IO, Int]] = Ref.of[IO, Int](0)

for
  ref <- counter()
  a   <- ref.updateAndGet(_ + 1) // 1
  b   <- ref.updateAndGet(_ + 1) // 2
yield (a, b)

Concurrency

import cats.effect.{IO, Ref}
import cats.syntax.parallel.*

def processAll(requests: List[Request], processed: Ref[IO, Int]): IO[Unit] =
  requests.parTraverse(req => handle(req) *> processed.update(_ + 1)).void

Error Handling

enum OrderError:
  case EmptyCart
  case UnverifiedCustomer(customerId: String)

class OrderService:
  def placeOrder(cart: Cart, customer: Customer): Either[OrderError, Order] =
    for
      _ <- Either.cond(cart.items.nonEmpty, (), OrderError.EmptyCart)
      _ <- Either.cond(customer.isVerified, (), OrderError.UnverifiedCustomer(customer.id))
    yield Order(cart, customer)

Immutability

def sumPositive(numbers: List[Int]): Int =
  numbers.filter(_ > 0).sum

case class RequestCounter(count: Int = 0):
  def increment: RequestCounter = copy(count = count + 1)

Implicits & Givens

trait JsonEncoder[T]:
  def encode(value: T): String

given JsonEncoder[User] with
  def encode(value: User): String = s"""{"name":"${value.name}"}"""

def render[T](value: T)(using encoder: JsonEncoder[T]): String =
  encoder.encode(value) // resolved from scope for whatever T the caller passes, no manual threading

API Design

final case class Email private (value: String):
  def domain: String = value.split("@").last

object Email:
  def parse(raw: String): Either[String, Email] =
    Either.cond(raw.contains("@"), new Email(raw), s"invalid email: $raw")

Collections

def totalActive(orders: List[Order]): BigDecimal =
  orders
    .filter(_.status == OrderStatus.Active)
    .foldLeft(BigDecimal(0))(_ + _.amount)

Pattern Matching

enum Shape:
  case Circle(radius: Double)
  case Rectangle(width: Double, height: Double)
  case Triangle(base: Double, height: Double)

def area(shape: Shape): Double = shape match
  case Shape.Circle(r)       => math.Pi * r * r
  case Shape.Rectangle(w, h) => w * h
  case Shape.Triangle(b, h)  => 0.5 * b * h
  // no default — compiler verifies this covers every Shape case

For-Comprehensions

def shippingQuote(userId: String): Option[BigDecimal] =
  for
    address <- findAddress(userId)
    weight  <- findWeightKg(userId)
  yield address.zone.ratePerKg * weight

Naming

trait PaymentGateway:
  def charge(amount: BigDecimal): Unit

class OrderService(gateway: PaymentGateway)

Scaladoc

/** Charges `amount` against the configured payment gateway.
  *
  * @return `Left(PaymentError.InsufficientFunds)` when the gateway declines the charge,
  *         `Left(PaymentError.GatewayUnavailable)` when the gateway cannot be reached,
  *         `Right(receipt)` otherwise.
  */
def charge(amount: BigDecimal): Either[PaymentError, Receipt] = ???

See Also

• scala-testing - Test-writing best practices for MUnit, ScalaTest, ScalaCheck, and mocking discipline
• scala-tooling - Build, compiler flags, Scalafix, Scalafmt, Scalastyle, and Wartremover rules