Minimal style guidelines with a subset enforced by Scalastyle.
We're following the official Scala Style Guide along with Twitter's "Effective Scala" guide. The goal is to keep our codebase readable and consistent.
A quote from Effective Scala.
The specifics of code formatting — so long as they are practical — are of little consequence. By definition style cannot be inherently good or bad and almost everybody differs in personal preference. However the consistent application of the same formatting rules will almost always enhance readability. A reader already familiar with a particular style does not have to grasp yet another set of local conventions, or decipher yet another corner of the language grammar.
The current MO is if you can't easily cite the style rule in the above noted references, we don't enforce it. It is likely a personal preference. Feel free to file a ticket for consideration in later style guide updates.
Scalastyle is used to check stuff that has an algorithm for checking. If something fails, fix it. Otherwise, err on the side of avoiding debates about edge cases. File a ticket or make an improved scalastyle checker for use.
sbt scalastyleTurn on the Scalastyle checker by selecting Settings -> Editor -> Inspections and "Scala style inspection.
Afterwards, you should see code issues highlighted. See #95 for some notes on updating the IDE to correctly auto-format. Note that there may be a minor lag between when you type and when IntelliJ's highlighting reflects the updated scalastyle check. Run via SBT for the latest.
We currently do not have the style checks enforced by Git or GitHub. You could add a custome git hook, but instructions are not yet present here.
Scalastyle includes support for disabling the checker via comments. Use as needed. If the algorithm needs improvement, please file a ticket and try to submit a patch.
Slick migrations and database migrations in general can have blocks of SQL ignored with this example strategy.
// scalastyle:off
class V1__InitialSchema extends JdbcMigration with SlickMigration with LazyLogging {
override def slickMigrate(db: DatabaseDef): Future[Any] = {
...
}
}
// scalastyle:onThese are only intended to speed up learning typical expected formatting and avoiding being frustrated when a style check fails and you can't figure out how to fix it.
If it fits on one line, then make one line.
class Foo extends Bar with MyTrait {
...If it needs more than one line, use 4-spaced params and 2-paced extends
or with.
class ImportFastaServiceType(
dbActor: ActorRef,
userActor: ActorRef,
engineManagerActor: ActorRef,
authenticator: Authenticator,
serviceStatusHost: String,
port: Int)
extends JobTypeService
with LazyLogging {
...If using a self-type that then uses with.
trait ImportFastaServiceTypeProvider {
this: JobsDaoActorProvider
with AuthenticatorProvider
with UserServiceActorRefProvider
with EngineManagerActorProvider
with SmrtLinkConfigProvider
with JobManagerServiceProvider =>
...See Effective Scala's comment section. It overrides default scaladoc.
Use ScalaDoc to provide API documentation. Use the following style:
/** * ServiceBuilder builds services * ... */but not the standard ScalaDoc style:
/** ServiceBuilder builds services * ... */
See PacificBiosciences/smrtflow#95 for the initial PR and discussion.