## Scala

### Introduction

Writing programs in Scala is fun. It enables developers to write
concise code that is free of boilerplate and enables readers to focus
on business logic. It does this in two principle ways. First, it
encourages a functional programming style, but still makes it easy to
fall back to an imperative approach when needed. Second, it has a
strong typesystem that is strict and sound enough to help catch many
classes of programming errors at compile time, yet is unobtrusive
enough to enable developers to work quickly and without requiring an
IDE.

Scala is considered to be an "unopinionated" language, and many styles
are seen across multiple organisations. Our approach to idiomatic
Scala is the following:

- It is simple (this may be different from "easy"). It is concise and
  focuses on business logic.
- It is functional, but not purely functional. We use state when it
  makes sense. Sometimes state actually improves readability of code.
- It is also not "Java++". We do allow and encourage the occasional
  implicit. Strongly typed is preferred to stringly typed.
- It may borrow ideas from category theory, but those ideas aren't a
  prerequisite for the reader. No need to know what a monad is.
- It is beyond typelevel programming. Typesafety is very valuable,
  however only within bounds. Shoehorning a full domain model into a
  single typesafe library has its own set of drawbacks, such as code
  size, compilation time, and tight coupling.

As an extra benefit, we encourage libraries to be compilable with
ScalaJS and Scala Native.


### Guidelines

- First and foremost, follow [the Principle of Least
  Power](http://www.lihaoyi.com/post/StrategicScalaStylePrincipleofLeastPower.html#philosophy-principle-of-least-power).
  
  In a nutshell:

  - Keep your code simple and at a level of abstraction dictated by
	the actual circumstances.
	
	
  - Don't design an API that will fit all future requirements. Start
	simple and refactor when the time comes. A good rule of thumb is
	to assume that you will completely rewrite your code at least once
	before finding a satisfactory solution.

  Rationale: the article justifies its points thoroughly. In general,
  Scala makes it easy to design advanced abstractions which can make
  it harder for an outsider to grasp a codebase. As a codebase grows,
  sometimes these abstractions become necessary, however they usually
  aren't in the beginning. Since Scala is a statically typed language,
  you should not fear refactoring when they do become necessary.
  
  *Scala's name comes from "scalable language". That refers to large,
  as well as small!*

- Avoid building libraries in such a way that they require wildcard
  imports to function.
  
  I.e. avoid building libraries that use this common pattern: `import
  foo.bar._`
  
  Rationale: a developer using a library doesn't want to know how it
  works, but wants to get his or her job done. Wildcard imports
  (especially if they bring into scope implicits) obfuscate the origin
  of types and methods to a reader who is not familiar with the
  library, and hence make it harder for the reader to edit.

- Choose dependencies on external libraries judiciously, and keep them
  to a minimum. Avoid depending on multiple libraries that offer
  similar functionality.

  Prefer reimplementing *small* features in your own code rather than
  relying on a library.

  For example, assume a web service has a REST API and also offers a
  Java library that wraps said API. In the case where only a couple of
  endpoints from the external REST service are required in some code,
  prefer calling the endpoints with an HTTP client directly, rather
  than relying on the entire library. This allows you to forego an
  additional layer of indirection and keeps you in control of which
  HTTP client to use.

- In public interfaces, expose only types from the Scala standard
  library. In particular, avoid exposing scalaz or cats types.

- Make use of comments liberally. Describe interesting parts of code,
  how to use it and why it's there. Don't comment *everything*.

- Organise code in a functionally cohesive manner. Use one parent
  package to namespace a library, and use nested packages according to
  functionality.
  
- Do not use runtime reflection.
  
  Rationale: runtime reflection circumvents type checking and strongly
  ties applications to the JVM.

- Use
  [scalafmt](https://scalameta.org/scalafmt/docs/introduction.html) to
  format code.
  
  Rationale: formatting is material for holy wars. If it is enforced
  by an automatic tool then there is no room for such discussions.

## Other Resources

[Simple Made
Easy](https://www.infoq.com/presentations/Simple-Made-Easy), by Rich
Hickey. A great talk about the differences between "Simple",
"Complex", "Easy" and "Hard", and how to write simple programs.