databricks/scala-style-guide

databricks/scala-style-guide

Description: Databricks Scala Coding Style Guide

Stars: 2798

Forks: 579

Open issues: 14

Created: 2015-03-10T02:14:03Z

Pushed: 2024-04-05T20:02:09Z

Default branch: master

Fork: no

Archived: no

README:

Databricks Scala Guide

At Databricks, our engineers work on some of the most actively developed Scala codebases in the world, including our own internal repo called "universe" as well as the various open source projects we contribute to, e.g. Apache Spark and Delta Lake. This guide draws from our experience coaching and working with our engineering teams as well as the broader open source community.

Code is __written once__ by its author, but __read and modified multiple times__ by lots of other engineers. As most bugs actually come from future modification of the code, we need to optimize our codebase for long-term, global readability and maintainability. The best way to achieve this is to write simple code.

Scala is an incredibly powerful language that is capable of many paradigms. We have found that the following guidelines work well for us on projects with high velocity. Depending on the needs of your team, your mileage might vary.

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Table of Contents

1. [Document History](#history)

2. [Syntactic Style](#syntactic)

• [Naming Convention](#naming)
• [Variable Naming Convention](#variable-naming)
• [Line Length](#linelength)
• [Rule of 30](#rule_of_30)
• [Spacing and Indentation](#indent)
• [Blank Lines (Vertical Whitespace)](#blanklines)
• [Parentheses](#parentheses)
• [Curly Braces](#curly)
• [Long Literals](#long_literal)
• [Documentation Style](#doc)
• [Ordering within a Class](#ordering_class)
• [Imports](#imports)
• [Pattern Matching](#pattern-matching)
• [Infix Methods](#infix)
• [Anonymous Methods](#anonymous)

1. [Scala Language Features](#lang)

• [Case Classes and Immutability](#case_class_immutability)
• [apply Method](#apply_method)
• [override Modifier](#override_modifier)
• [Destructuring Binds](#destruct_bind)
• [Call by Name](#call_by_name)
• [Multiple Parameter Lists](#multi-param-list)
• [Symbolic Methods (Operator Overloading)](#symbolic_methods)
• [Type Inference](#type_inference)
• [Return Statements](#return)
• [Recursion and Tail Recursion](#recursion)
• [Implicits](#implicits)
• [Exception Handling (Try vs try)](#exception)
• [Options](#option)
• [Monadic Chaining](#chaining)
• [Symbol Literals](#symbol)

1. [Concurrency](#concurrency)

• [Scala concurrent.Map](#concurrency-scala-collection)
• [Explicit Synchronization vs Concurrent Collections](#concurrency-sync-vs-map)
• [Explicit Synchronization vs Atomic Variables vs @volatile](#concurrency-sync-vs-atomic)
• [Private Fields](#concurrency-private-this)
• [Isolation](#concurrency-isolation)

1. [Performance](#perf)

• [Microbenchmarks](#perf-microbenchmarks)
• [Traversal and zipWithIndex](#perf-whileloops)
• [Option and null](#perf-option)
• [Scala Collection Library](#perf-collection)
• [private[this]](#perf-private)

1. [Java Interoperability](#java)

• [Java Features Missing from Scala](#java-missing-features)
• [Traits and Abstract Classes](#java-traits)
• [Type Aliases](#java-type-alias)
• [Default Parameter Values](#java-default-param-values)
• [Multiple Parameter Lists](#java-multi-param-list)
• [Varargs](#java-varargs)
• [Implicits](#java-implicits)
• [Companion Objects, Static Methods and Fields](#java-companion-object)

1. [Testing](#testing)

• [Intercepting Exceptions](#testing-intercepting)

1. [Miscellaneous](#misc)

• [Prefer nanoTime over currentTimeMillis](#misc_currentTimeMillis_vs_nanoTime)
• [Prefer URI over URL](#misc_uri_url)
• [Prefer existing well-tested methods over reinventing the wheel](#misc_well_tested_method)

Document History

• 2015-03-16: Initial version.
• 2015-05-25: Added [override Modifier](#override_modifier) section.
• 2015-08-23: Downgraded the severity of some rules from "do NOT" to "avoid".
• 2015-11-17: Updated [apply Method](#apply_method) section: apply method in companion object should return the companion class.
• 2015-11-17: This guide has been [translated into Chinese](README-ZH.md). The Chinese translation is contributed by community member Hawstein. We do not guarantee that it will always be kept up-to-date.
• 2015-12-14: This guide has been [translated into Korean](README-KO.md). The Korean translation is contributed by Hyukjin Kwon and reviewed by Yun Park, Kevin (Sangwoo) Kim, Hyunje Jo and Woochel Choi. We do not guarantee that it will always be kept up-to-date.
• 2016-06-15: Added [Anonymous Methods](#anonymous) section.
• 2016-06-21: Added [Variable Naming Convention](#variable-naming) section.
• 2016-12-24: Added [Case Classes and Immutability](#case_class_immutability) section.
• 2017-02-23: Added [Testing](#testing) section.
• 2017-04-18: Added [Prefer existing well-tested methods over reinventing the wheel](#misc_well_tested_method) section.
• 2019-12-18: Added [Symbol Literals](#symbol) section.
• 2022-08-05: Updated [Monadic Chaining](#chaining) section: do not monadic-chain with an if-else block.

Syntactic Style

Naming Convention

We mostly follow Java's and Scala's standard naming conventions.

• Classes, traits, objects should follow Java class convention, i.e. PascalCase style.

class ClusterManager

trait Expression

• Packages should follow Java package naming conventions, i.e. all-lowercase ASCII letters.

package com.databricks.resourcemanager

• Methods/functions should be named in camelCase style.

• Constants should be all uppercase letters and be put in a companion object.

object Configuration {
val DEFAULT_PORT = 10000
}

• An enumeration class or object which extends the Enumeration class shall follow the convention for classes and objects, i.e. its name should be in PascalCase style. Enumeration values shall be in the upper case with words separated by the underscore character _. For example:

private object ParseState extends Enumeration {
type ParseState = Value

val PREFIX,
TRIM_BEFORE_SIGN,
SIGN,
TRIM_BEFORE_VALUE,
VALUE,
VALUE_FRACTIONAL_PART,
TRIM_BEFORE_UNIT,…