Files [Edit]
- Single-Unit files.
- Multi-Unit files.
- Naming Conventions
Types should be organized to promote long-term maintenance and development. For single-unit files (including the case
of a class/trait and its companion), Java naming and placement conventions should be preferred, despite Scala allowing
for greater flexibility in this regard. Developers may optionally choose to use multi-unit files when required by the
language or when placing the types in a single file promotes maintainability.
Single-Unit files.
Generally, “single-unit” files include those containing a single top-level definition, meaning an un-nested class, trait
or object. Additionally, this section also applies to classes or traits that have companion objects. Companion objects
should be grouped with their corresponding class or trait in the same file.
Using single-unit files is always allowed as a default organizational choice.
package com.bizo.file
class BizoFile { ... }
object BizoFile { ... }
Multi-Unit files.
Other than the case of companion objects, there are two cases where developers may choose to place multiple units in a
single file.
First, multiple compilation units should be placed in the same file if this is required by the Scala language. One
common example is that of a sealed trait and several sub-classes or sub-objects.
package com.bizo.teams
sealed trait BizoTeam
case object AppsTeam extends BizoTeam
case object DataTeam extends BizoTeam
case object InfrastructureTeam extends BizoTeam
case class AdHocTeam(name: String) extends BizoTeam
Second, multiple compilation units should be placed in the same file when multiple classes logically form a single,
cohesive group, sharing concepts to the point where maintenance is served by containing them within a single file.
These situations are harder to predict than the aforementioned sealed supertype exception. Generally speaking, if it is
easier to perform long-term maintenance and development on several units in a single file rather than spread across
multiple, then such an organizational strategy should be preferred for these classes. However, keep in mind that when
multiple units are contained within a single file, it is often more difficult to find specific units when it comes time
to make changes.
Naming Conventions
The goal of a filename is to both give an indication of what is inside the file and assist a developer in knowing where
to look for the units contained in that file. If the name does not assist in understanding what is in the file, the
developer should either pick a more explanatory name or split the contents into multiple files.
Single-unit files (including those containing only a trait/class and its companion) should obey the Java naming convention.
i.e., the file containing the BizoFile class (and companion object) should be named BizoFile.scala.
Multiple-unit files should be given camelCase names with a lower-case first letter. This convention differentiates
multi-unit from single-unit files, greatly easing the process of finding declarations. If the file contains a single
obvious type that is more significant than the others (e.g. a root type like the BizoTeam trait for the example above),
the file should be named after that type (e.g. bizoTeam.scala). If there is no dominant type in the file, filenames
should be descriptive of the logical property shared by all units within (e.g. ast.scala).
Files whose dominant (or only) type is the package object should be named “package.scala”.
Not being able to think of a good filename is a strong indication that the file contains unrelated concepts!
In all cases, files should be placed in the directory corresponding to the package of the primary type(s) that they
contain. e.g., the bizoTeam.scala file should be placed in com/bizo/teams. As packages should also group related
classes together, we expect that most files will contain only types living under this primary package.