This page is no longer maintained — Please continue to the home page at www.scala-lang.org

Re: [scalaz] Re: problems of scala complexity

2 replies
Kevin Wright 2
Joined: 2010-05-30,
User offline. Last seen 26 weeks 4 days ago.
So, in order to avoid disagreement over the semantic meaning of "documentation".  Would it it fair to say everyone agrees that scalaz lacks a centralised set of *tutorials* explaining the concepts involved and some real-world use cases?
That's certainly a cause I could get behind...

On 20 November 2011 14:16, Josh Suereth <joshua [dot] suereth [at] gmail [dot] com> wrote:

Exactly my point!   Heck, I'm a guy who want applicative functor syntactic sugar like for-expressions provide for monadic thing.   Scalaz is *useful*.   It's unnecessarily hard to learn the simmer concepts.  I think this can be improved, and I hate when people point to this as a form of complexity.

On Nov 20, 2011 9:01 AM, "Anwar Rizal" <anrizal05 [at] gmail [dot] com> wrote:
My approach to scalaz is actually quite different. After using quite a while Scala, I realize that standard library has some limits.

For example, I need to have map that works with Either, or map that works correctly with java collection (scala.collection.JavaConversions sucks :-). I also discovered later applicative functor through

some(3) |@| some(5) {_ + _ }

then,

either Right(4) |@| Left("Error') {_ + _}  === Left("Error")

without necessarily understanding the whole world of functor or applicative.

Those examples are useful and damn simple and I'm sure we can find a lot of pearl out there in scalaz without having to understanding each and every type class existing out there. Scalaz validation and monoid look to enter to this category too (easy to use).

I don't 100% agree even with "Scalaz uses very advanced topics". Scalaz is indeed implemented using this advanced topic, but one does not need to understand the implementation to work with Scalaz.

That said, the beginners like me don't find those things easily. Often, I had to go to the codes to discover those things.
Maybe a better documentation or more centralized tutorial will be helpful. It's always more comfortable to have the tutorial in one place than have to wander around a lot of blogs that you're not sure about their quality.

- Anwar

On Sun, Nov 20, 2011 at 1:44 PM, Josh Suereth <joshua [dot] suereth [at] gmail [dot] com> wrote:

Jason -

I think, as always, you're doing some amazing work on scalaz.   The most recent scalaz7 refactorings will provide far more utility, but I think need more documentation for folks to understand.

I'm willing to help write scalaz Docs.   Hell, I put a  category theory chapter in my book.

My point, for others, is not to use scalaz as a bastion of how complex scala is.   Scalaz uses very advanced topics with little internal documentation, so people assume that this means the library is as complex as the learning curve.  I think sbt 0.10 is in a similar vein.   Those of us who *have* learned the concepts see how simple things are to use, but learning is difficult.

Sbt just got a users guide.   I'm more than willing to help scalaz with documentation.    I've been watching scalaz7 with excitement and anticipation.  

Maybe in Scalaz7 we can add a good amount of learning material.

On Nov 20, 2011 4:09 AM, "Jason Zaugg" <jzaugg [at] gmail [dot] com> wrote:
On Sat, Nov 19, 2011 at 7:44 PM, Josh Suereth <joshua [dot] suereth [at] gmail [dot] com> wrote:
I completely disagree with the assumption that FP style code can't be engineered by many.   Scalaz does itself a disservice in two ways:
(1)  Non-existent documentation.   This is *just as bad* as that old legacy codebase we're all forced to maintain with 1k's of lines of non-documented junk code. (2) Re-inventing itself every revision.    Scalaz is tough because it changes so frequently.  Luckily 6.x series has been maintained for a while and stable-ish.
Assuming the Scalaz represents functional programming in scala on the whole is bogus.

Hi Josh,
Let me address your second point. 
Scalaz 6.x was structurally the same as 5.x. The changes were additive [1] and were largely source compatible.
The 5.x series differed from 4.x in order to take advantage of the type inference abilities in Scala 2.8.0.
However, Scalaz 7 will mark a change in design. This is required to help us address three challenges: 
 1) reconciling the tension between type classes and inheritance (both type classes inheriting from each other, and the classified types inheriting from each other),  2) organizing implicits to avoid ambiguity using the relatively limited tools available to influence implicit search  3) providing library functionality a-la-carte, without requiring (although still supporting) the "uber" import of Scalaz._ or even the use of implicit views, while still maximising type inference.
We don't take this choice lightly. Firstly, it represents a huge job for us to move things around, but despite this we've tried out three distinct approaches to help us prove the new design. I'm really excited about the solution we've have adopted. I've started to document it's design principles [2] [3]. I plan to write this up more thoroughly, as I think it's of general interest to anyone designing and using type classes in Scala.
I'm also mindful of ways to make the library more learnable: providing examples around 'standalone' usage of type classes to avoid the distraction of the 'syntactic' implicit conversions; consistently making methods like flatMap / ap / foldRight directly available on data structures, rather than only via the related type class instance, and modularizing the library to limit the size of scalaz-core.
In recognition of the breaking nature of this release, we will maintain the 6.x series on a bug-fix basis well into 2012.
Could we use a bit more ScalaDoc? Sure! Personally, I don't think that your proposed documentation for Functor (from another thread) added *that* much value, when weighed against the time needed to write it, and extra maintenance cost (automatic refactoring tools don't work yet for Scaladoc). But you might notice that documentation *is* being added in some places (e.g. DList [4]), and we will continue in this style.
I'm cross-posting to [scalaz]; I suggest we move any followup questions over there. You can also email me directly with questions or suggestions.
-jason
[1] http://code.google.com/p/scalaz/wiki/Scalaz6 [2] https://github.com/scalaz/scalaz/blob/scalaz-seven/README.md[3] https://github.com/scalaz/scalaz/blob/scalaz-seven/doc/DeveloperGuide.md [4] https://github.com/scalaz/scalaz/commit/7b8ba0fe3cf51ad721e7fd8502167d62de2cbe2c


Anwar Rizal
Joined: 2011-07-05,
User offline. Last seen 42 weeks 5 days ago.
Re: problems of scala complexity

And if possible, the tutorials do not refer Java or Haskell.

On Nov 20, 3:25 pm, Kevin Wright wrote:
> So, in order to avoid disagreement over the semantic meaning of
> "documentation".  Would it it fair to say everyone agrees that scalaz lacks
> a centralised set of *tutorials* explaining the concepts involved and some
> real-world use cases?
>
> That's certainly a cause I could get behind...
>
> On 20 November 2011 14:16, Josh Suereth wrote:
>
>
>
>
>
>
>
> > Exactly my point!   Heck, I'm a guy who want applicative functor syntactic
> > sugar like for-expressions provide for monadic thing.   Scalaz is
> > *useful*.   It's unnecessarily hard to learn the simmer concepts.  I think
> > this can be improved, and I hate when people point to this as a form of
> > complexity.
> > On Nov 20, 2011 9:01 AM, "Anwar Rizal" wrote:
>
> >> My approach to scalaz is actually quite different. After using quite a
> >> while Scala, I realize that standard library has some limits.
>
> >> For example, I need to have map that works with Either, or map that works
> >> correctly with java collection (scala.collection.JavaConversions sucks :-).
> >> I also discovered later applicative functor through
>
> >> some(3) |@| some(5) {_ + _ }
>
> >> then,
>
> >> either Right(4) |@| Left("Error') {_ + _}  === Left("Error")
>
> >> without necessarily understanding the whole world of functor or
> >> applicative.
>
> >> Those examples are useful and damn simple and I'm sure we can find a lot
> >> of pearl out there in scalaz without having to understanding each and every
> >> type class existing out there. Scalaz validation and monoid look to enter
> >> to this category too (easy to use).
>
> >> I don't 100% agree even with "Scalaz uses very advanced topics". Scalaz
> >> is indeed implemented using this advanced topic, but one does not need to
> >> understand the implementation to work with Scalaz.
>
> >> That said, the beginners like me don't find those things easily. Often, I
> >> had to go to the codes to discover those things.
> >> Maybe a better documentation or more centralized tutorial will be
> >> helpful. It's always more comfortable to have the tutorial in one place
> >> than have to wander around a lot of blogs that you're not sure about their
> >> quality.
>
> >> - Anwar
>
> >> On Sun, Nov 20, 2011 at 1:44 PM, Josh Suereth wrote:
>
> >>> Jason -
>
> >>> I think, as always, you're doing some amazing work on scalaz.   The most
> >>> recent scalaz7 refactorings will provide far more utility, but I think need
> >>> more documentation for folks to understand.
>
> >>> I'm willing to help write scalaz Docs.   Hell, I put a  category theory
> >>> chapter in my book.
>
> >>> My point, for others, is not to use scalaz as a bastion of how complex
> >>> scala is.   Scalaz uses very advanced topics with little internal
> >>> documentation, so people assume that this means the library is as complex
> >>> as the learning curve.  I think sbt 0.10 is in a similar vein.   Those of
> >>> us who *have* learned the concepts see how simple things are to use, but
> >>> learning is difficult.
>
> >>> Sbt just got a users guide.   I'm more than willing to help scalaz with
> >>> documentation.    I've been watching scalaz7 with excitement and
> >>> anticipation.
>
> >>> Maybe in Scalaz7 we can add a good amount of learning material.
> >>> On Nov 20, 2011 4:09 AM, "Jason Zaugg" wrote:
>
> >>>> On Sat, Nov 19, 2011 at 7:44 PM, Josh Suereth >>>> > wrote:
>
> >>>>> I completely disagree with the assumption that FP style code can't be
> >>>>> engineered by many.   Scalaz does itself a disservice in two ways:
>
> >>>>> (1)  Non-existent documentation.   This is *just as bad* as that old
> >>>>> legacy codebase we're all forced to maintain with 1k's of lines of
> >>>>> non-documented junk code.
> >>>>> (2) Re-inventing itself every revision.    Scalaz is tough because it
> >>>>> changes so frequently.  Luckily 6.x series has been maintained for a while
> >>>>> and stable-ish.
>
> >>>>> Assuming the Scalaz represents functional programming in scala on the
> >>>>> whole is bogus.
>
> >>>> Hi Josh,
>
> >>>> Let me address your second point.
>
> >>>> Scalaz 6.x was structurally the same as 5.x. The changes were additive
> >>>> [1] and were largely source compatible.
>
> >>>> The 5.x series differed from 4.x in order to take advantage of the type
> >>>> inference abilities in Scala 2.8.0.
>
> >>>> However, Scalaz 7 will mark a change in design. This is required to
> >>>> help us address three challenges:
>
> >>>>  1) reconciling the tension between type classes and inheritance (both
> >>>> type classes inheriting from each other, and the classified types
> >>>> inheriting from each other),
> >>>>  2) organizing implicits to avoid ambiguity using the relatively
> >>>> limited tools available to influence implicit search
> >>>>  3) providing library functionality a-la-carte, without requiring
> >>>> (although still supporting) the "uber" import of Scalaz._ or even the use
> >>>> of implicit views, while still maximising type inference.
>
> >>>> We don't take this choice lightly. Firstly, it represents a huge job
> >>>> for us to move things around, but despite this we've tried out three
> >>>> distinct approaches to help us prove the new design. I'm really excited
> >>>> about the solution we've have adopted. I've started to document it's design
> >>>> principles [2] [3]. I plan to write this up more thoroughly, as I think
> >>>> it's of general interest to anyone designing and using type classes in
> >>>> Scala.
>
> >>>> I'm also mindful of ways to make the library more learnable: providing
> >>>> examples around 'standalone' usage of type classes to avoid the distraction
> >>>> of the 'syntactic' implicit conversions; consistently making methods like
> >>>> flatMap / ap / foldRight directly available on data structures, rather than
> >>>> only via the related type class instance, and modularizing the library to
> >>>> limit the size of scalaz-core.
>
> >>>> In recognition of the breaking nature of this release, we will maintain
> >>>> the 6.x series on a bug-fix basis well into 2012.
>
> >>>> Could we use a bit more ScalaDoc? Sure! Personally, I don't think that
> >>>> your proposed documentation for Functor (from another thread) added *that*
> >>>> much value, when weighed against the time needed to write it, and extra
> >>>> maintenance cost (automatic refactoring tools don't work yet for Scaladoc).
> >>>> But you might notice that documentation *is* being added in some places
> >>>> (e.g. DList [4]), and we will continue in this style.
>
> >>>> I'm cross-posting to [scalaz]; I suggest we move any followup questions
> >>>> over there. You can also email me directly with questions or suggestions.
>
> >>>> -jason
>
> >>>> [1]http://code.google.com/p/scalaz/wiki/Scalaz6
> >>>> [2]https://github.com/scalaz/scalaz/blob/scalaz-seven/README.md
> >>>> [3]
> >>>>https://github.com/scalaz/scalaz/blob/scalaz-seven/doc/DeveloperGuide.md
> >>>> [4]
> >>>>https://github.com/scalaz/scalaz/commit/7b8ba0fe3cf51ad721e7fd8502167...

Chris Marshall
Joined: 2009-06-17,
User offline. Last seen 44 weeks 3 days ago.
RE: [scalaz] Re: problems of scala complexity
How is Nick Partridge's "Deriving Scalaz" ([1] - linked to from the scalaz google home page) not a tutorial of sorts? And what about Jason's presentations about the structure of the library? And (to Josh Suereth); Nick's talk also contains a detailed explanation of Validation and the point of ValidationNEL in terms of failure accumulation; that presentation is more than a year and a half old
What makes me laugh about this is the calls of "scalaz has no documentation". What about scala itself? The latest scaladoc for actor [2] is just appalling - it doesn't even say what an Actor is, or mention messages once. Not even once! I read a whole chapter on actors in PiS and still came out having no idea whether an actor could process multiple messages at the same time [3]. It's always the same with documentation - those who wrote the library are so fundamentally close to the subject matter that they cannot possibly write documentation of use to those approaching it for the first time.
I would simply not have used scalaz if I didn't feel it had documentation. Seriously - I have rejected many other libraries (PicoContainer, anyone?) for this exact same reason. It's just that the scalaz documentation was provided in the form of a suite of tests and examples.
Chris
[1] http://vimeo.com/10482466[2] http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html#scala.actors.Actor[3] http://stackoverflow.com/questions/1007010/can-scala-actors-process-multiple-messages-simultaneously

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland