A collection of best practices, friendly to people that want to contribute.

• Version: 1.2
• Updated at: 2016-06-08

• 0. Preface

  • 0.1 MUST NOT follow advice blindly

• 1. Hygienic Rules

  • 1.1. SHOULD enforce a reasonable line length
  • 1.2. MUST NOT rely on a SBT or IDE plugin to do the formatting for you
  • 1.3. SHOULD break long functions
  • 1.4. MUST NOT introduce spelling errors in names and comments
  • 1.5. Names MUST be meaningful

• 2. Language Rules

  • 2.1. MUST NOT use "return"
  • 2.2. SHOULD use immutable data structures
  • 2.3. SHOULD NOT update a "var" using loops or conditions
  • 2.4. SHOULD NOT define useless traits
  • 2.5. MUST NOT use "var" inside a case class
  • 2.6. SHOULD NOT declare abstract "var" members
  • 2.7. MUST NOT throw exceptions for validations of user input or flow control
  • 2.8. MUST NOT catch Throwable
  • 2.9. MUST NOT use "null"
  • 2.10. MUST NOT use "Option.get"
  • 2.11. MUST NOT use Java's Date or Calendar, instead use java.time (JSR-310)
  • 2.12. SHOULD NOT use Any or AnyRef or isInstanceOf / asInstanceOf
  • 2.13. MUST serialize dates as either Unix Timestamp or ISO 8601
  • 2.14. MUST NOT use magic values
  • 2.15. SHOULD NOT use "var" as shared state
  • 2.16. Public functions SHOULD have an explicit return type
  • 2.17. SHOULD NOT define case classes nested in other classes
  • 2.18. MUST NOT include classes, traits and objects inside package objects

• 3. Application Architecture

  • 3.1. SHOULD NOT use the Cake pattern
  • 3.2. MUST NOT put things in Play's Global
  • 3.3. SHOULD NOT apply optimizations without profiling
  • 3.4. SHOULD be mindful of the garbage collector
  • 3.5. MUST NOT use parameterless ConfigFactory.load() or access a Config object directly

• 4. Concurrency and Parallelism

  • 4.1. SHOULD avoid concurrency like the plague it is
  • 4.2. SHOULD use appropriate abstractions only where suitable
  • 4.3. SHOULD NOT wrap purely CPU-bound operations in Futures
  • 4.4. MUST use Scala's BlockContext on blocking I/O
  • 4.5. SHOULD NOT block
  • 4.6. SHOULD use a separate thread-pool for blocking I/O
  • 4.7. All public APIs SHOULD BE thread-safe
  • 4.8. SHOULD avoid contention on shared reads
  • 4.9. MUST provide a clearly defined and documented protocol for each component or actor that communicates over async boundaries
  • 4.10. SHOULD always prefer single producer scenarios
  • 4.11. MUST NOT hard-code the thread-pool / execution context

• 5. Akka Actors

  • 5.1. SHOULD evolve the state of actors only in response to messages received from the outside
  • 5.2. SHOULD mutate state in actors only with "context.become"
  • 5.3. MUST NOT leak the internal state of an actor in asynchronous closures
  • 5.4. SHOULD do back-pressure
  • 5.5. SHOULD NOT use Akka FSM

Open an issue to make suggestions, or create a pull request ;-)

Copyright © 2015-2016, Some Rights Reserved.
Licensed under CC BY 4.0.