Document naming implicits according to @non s comment in #1061 #1920
Conversation
tbje
commented
Sep 20, 2017
tbje
commented
- fixing Document implicit naming convention #1841.
docs/src/main/tut/guidelines.md
Outdated
| - 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`. |
There was a problem hiding this comment.
Thanks so much! We actually also include the package name in the name now.
catsPackageNameTypeclassNameForDataStruct
There was a problem hiding this comment.
Thank you for letting me know. Would the following be correct ?
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.
- The type and the type class should be mentioned in the name.
As an example, for cats.kernel.Monoid[List[A]], the name of the implicit should be catsKernelMonoidForList.
There was a problem hiding this comment.
We should probably mention that in cats.instances we don't follow this rule and use catsStd.....
There was a problem hiding this comment.
The package used in the name is package where the instance is defined, your example gives the impression that it's the package where the type class is defined.
BTW, we are not really strictly following this rule, for instance, in cats.instances we named an instances as
catsStdInstancesForOption
https://github.com/typelevel/cats/blob/master/core/src/main/scala/cats/instances/option.scala#L8
here Std is to represent the package instances which used to be called std, we didn't change the name here because catsInstancesInstancesForOption would be weird.
the next word Instances in the name is used here because this instance is an instance for multiple type classes.
So we do have some flexibility here.
There was a problem hiding this comment.
My recommendation would be just
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 (where instance is defined) name.
* The type and the type class should be mentioned in the name.
* If the instance is for multiple type classes, use `InstancesFor` instead
* This rule is relatively flexible. Use what you see appropriate. The goal is to maintain the uniqueness and avoid conflicts.
There was a problem hiding this comment.
It seems like Std is used when the instance is for a Scala standard library type.
There was a problem hiding this comment.
I've gone through the instances with @tbje and as far as I can tell the current revision is correct in all cases.
Codecov Report
@@ Coverage Diff @@
## master #1920 +/- ##
==========================================
+ Coverage 95.54% 95.55% +<.01%
==========================================
Files 248 248
Lines 4426 4430 +4
Branches 116 117 +1
==========================================
+ Hits 4229 4233 +4
Misses 197 197
Continue to review full report at Codecov.
|
docs/src/main/tut/guidelines.md
Outdated
| - 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`. |
There was a problem hiding this comment.
This example may give the false impression that the package name is the package of the type class. How about
As an example, an implicit instance of `Monoid` for `List` defined in the package `Kernel` should be named as `catsKernelMonoidForList`
|
Thank you for guiding me ! |
