From ddb93739cdda9c461b5e7c3a0107d0e09e2221b9 Mon Sep 17 00:00:00 2001 From: Trond Sandnes Bjerkestrand Date: Wed, 20 Sep 2017 15:26:11 +0100 Subject: [PATCH 1/3] Document naming implicits according to @non s comment in #1061 - fixing #1841. --- docs/src/main/tut/guidelines.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/src/main/tut/guidelines.md b/docs/src/main/tut/guidelines.md index c0bbc82b8b..c8bc87e183 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,15 @@ 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" -- a third-party will less likely do this. +- The type and the type class should be mentioned in the name. + +As an example, for `Monoid[List[A]]`, the name of the implicit should be `catsMonoidForList`. + +#### TODO: Once we drop 2.10 support, AnyVal-extending class constructor parameters can be marked as private. From 69b56bef9dd9ace0bc06a05130bd607b9bd2026b Mon Sep 17 00:00:00 2001 From: Trond Sandnes Bjerkestrand Date: Wed, 20 Sep 2017 16:53:35 +0100 Subject: [PATCH 2/3] Adding more rules. --- docs/src/main/tut/guidelines.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/src/main/tut/guidelines.md b/docs/src/main/tut/guidelines.md index c8bc87e183..b7e652245e 100644 --- a/docs/src/main/tut/guidelines.md +++ b/docs/src/main/tut/guidelines.md @@ -74,10 +74,14 @@ to make this intermediate class a [Value Class](http://docs.scala-lang.org/overv 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" -- a third-party will less likely do this. +- 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, for `Monoid[List[A]]`, the name of the implicit should be `catsMonoidForList`. +As an example, for `cats.kernel.Monoid[List[A]]`, the name of the implicit should be `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. From a7ad647251e7677da8e863db7e498a16b06266a8 Mon Sep 17 00:00:00 2001 From: Trond Sandnes Bjerkestrand Date: Fri, 22 Sep 2017 13:09:24 +0100 Subject: [PATCH 3/3] Updating example to be more precise according to @kailuowang suggestion. --- docs/src/main/tut/guidelines.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/src/main/tut/guidelines.md b/docs/src/main/tut/guidelines.md index b7e652245e..79e203a9f7 100644 --- a/docs/src/main/tut/guidelines.md +++ b/docs/src/main/tut/guidelines.md @@ -80,7 +80,8 @@ therefore name our implicits according to the following rules: - 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, for `cats.kernel.Monoid[List[A]]`, the name of the implicit should be `catsKernelMonoidForList`. +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: