diff --git a/docs/src/main/tut/guidelines.md b/docs/src/main/tut/guidelines.md index 8eb6acf7b9..bc7e3b1c17 100644 --- a/docs/src/main/tut/guidelines.md +++ b/docs/src/main/tut/guidelines.md @@ -13,7 +13,7 @@ All guidelines in cats should have clear justifications. There is no room for tr ### Composing Implicit Conversions in Traits -Implicit syntax conversions provided in publicly-exposed traits should be marked final +Implicit syntax conversions provided in publicly-exposed traits should be marked final so that any composition of the traits provides conversions that can all be inlined. ### Ops Classes @@ -69,6 +69,20 @@ The user doesn't need to specify the type `A` which is given by the parameter. You probably noticed that there is a `val dummy: Boolean` in the `PurePartiallyApplied` class. This is a trick we used to make this intermediate class a [Value Class](http://docs.scala-lang.org/overviews/core/value-classes.html) so that there is no cost of allocation, i.e. at runtime, it doesn't create an instance of `PurePartiallyApplied`. We also hide this partially applied class by making it package private and placing it inside an object. +### Implicit naming -#### TODO: +In a widely-used library it's important to minimize the chance that the names of implicits will be used by others and +therefore name our implicits according to the following rules: + +- Implicits should start with "cats" followed by the package name (where the instance is defined). +- If the package contains `instances` leave `instances` out. +- The type and the type class should be mentioned in the name. +- If the instance is for multiple type classes, use `InstancesFor` instead of a type class name. +- If the instance is for a standard library type add `Std` after the package. i.e. `catsStdShowForVector` and `catsKernelStdGroupForTuple`. + +As an example, an implicit instance of `Monoid` for `List` defined in the package `Kernel` should be named `catsKernelMonoidForList`. + +This rule is relatively flexible. Use what you see appropriate. The goal is to maintain uniqueness and avoid conflicts. + +#### TODO: Once we drop 2.10 support, AnyVal-extending class constructor parameters can be marked as private.