Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document naming implicits according to @non s comment in #1061 #1920

Merged
merged 3 commits into from
Sep 23, 2017
Merged

Document naming implicits according to @non s comment in #1061 #1920

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ddb9373
Document naming implicits according to @non s comment in #1061
tbje Sep 20, 2017
69b56be
Adding more rules.
tbje Sep 20, 2017
a7ad647
Updating example to be more precise according to @kailuowang suggestion.
tbje Sep 22, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions docs/src/main/tut/guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ All guidelines in cats should have clear justifications. There is no room for tr

### <a id="implicit-syntax-conversions" href="#implicit-syntax-conversions"></a> 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.

### <a id="ops-classes" href="#ops-classes"></a> Ops Classes
Expand Down Expand Up @@ -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.

### <a id="ops-classes" href="#implicit-naming"></a> 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.