Use uber import in code examples

[ceedubs]

Currently we have both ScalaDoc examples (via sbt-doctest) and tutorials (via tut) that import specific typeclass instances (ex: import cats.std.option._). At the Typelevel summit in Philly, several people mentioned that they had seen people struggle a lot with imports. There seemed to be a consensus that we should use import cats.implicits._ in code samples to encourage people to start with the easier approach.

If users really want to be selective about what they bring into scope, then they can use more piecemeal imports. We should also provide some documentation (maybe even a flowchart?) for this use-case. However, I think more importantly we should use the uber import in code examples so people don't go down an unnecessary rabbit hole.

[EncodePanda]

I will be willing to contribute if u point to resources which should be updated.

[ceedubs]

@rabbitonweb thanks for volunteering! Let's wait for a couple maintainers to 👍 this to make sure we want to go forward with this before you put too much effort into it. @non @adelbertc @tpolecat?

To find the resources, the best approach I can think of is to grep for import cats.std and import cats.syntax and ignore the ones that are happening inside tests or at the top of source files. Really we just want things within /** ... */ blocks and tut sheds in .md files I think.

[peterneyens]

While this will undoubtably remove some confusion for those getting started with (a library like) cats, I find that examples with the specific imports help those a little farther down the road to understand what is going on. It is an easy way to make the connection between a function and the underlying type class. Trying to use the right imports at least helped/helps me to improve my understanding of the underlying concepts.

What I am trying to say is that while reducing the first step, it may increase the next.

I am not sure how to make it easy to find the specific imports.

• Creating a good and easy to use flowchart to get the specific imports is probably not an easy task (If I just want the import for |@|, I wouldn't want to look at something similar to these scalaz charts).
• Just commenting out the specific imports probably adds too much noise (especially for those getting started). Comments also don't seem to play nice with sbt-doctest.

import cats.implicits._
// import cats.std.list._
// import cats.std.option._
// import cats.syntax.option._
// import cats.syntax.traverse._

List(1.some, 2.some).sequence

I am not sure if this should stop us from going ahead and using the “uber” import everywhere, just felt it is something to consider.

[ceedubs]

@peterneyens thanks for sharing your thoughts. I definitely have a similar hesitation.

Ultimately I think I'd rather reduce the barrier for people who are new to the library (and possibly FP). If you get to the point where you really want to figure out how the piecemeal imports work, you are probably at a stage where you are willing to put a bit more effort into peaking under the hood.

I am not a big fan of the commented-out import approach, because it seems too prone to going outdated to me. I was thinking about something more along the lines of this flowchart (though there are some flaws in it). Sorry it's kind of awful to use on gliffy - I lost the png that I once had for it, and I've lost my gliffy credentials. The fact that this happened at a previous job seems like evidence to me that piecemeal imports can be an unnecessarily cumbersome barrier :). I think I'd also want a dedicated tut page for piecemeal imports where we have a number of (compiler-verified) examples that convey the general pattern and a few common cases that might trip people up.

[ceedubs]

@rabbitonweb are you still interested in working on this? From some gitter conversations it sounds like people are happy with moving forward on this.

[non]

I agree with @ceedubs. I want the global import to be what we advertise. I'm fine with people using piecemeal imports but the bar for them is necessarily a lot higher, and I don't want to give the impression that everyone else just psychically knows where they are (because we often don't and have to search the code). 👍

[ceedubs]

I think this is resolved after #1104 and #1115.