Time to encourage meaningful type parameter names? Discuss

People ascribe names to abstract things all the time.   When I say "fire", I may be referring to all my experiences of fire as an abstract concept.  Your mind interrupts it and ascribes the aspects of fire that it knows to the words I am using.
The same is true with names.  To Say that the more abstract a thing, the less important the name is BOGUS, bunk.   WHY oh why to we ascribe silly names to abstract concepts like:
Monad MonoidEigenvectorNullspacemonomorphismJacobian
My opinion is that the more abstract a concept, usually the longer or sillier the name (probably because they're named after the person who first *described* the abstract concept).
You see, if I give something a name and a description, I can start using the name in place of the description.   This is what language is all about. 
Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor to me at all.  Again, I can come up with a class Graph where these names make a *lot* of sense.
Even in the case of "def equals(that: Any): Boolean", we still use "that" or "rhs" instead of "x" or "y", Where "that" refers to "something that is not htis" and "rhs" refers to the right-hand-side of an expression.   These words connote *meaning* and only as much meaning as needed to determine what the variable is doing.

trait TypeFunctor {  type F[x]   def map[X, Y](f: X => Y): F[X] => F[Y]}
To those who don't understand the concepts of functors, these names are pretty poor.  However, if I *document* the concepts I'm using.
/** A type functor is a mapping between two categories of types.   A functor can take any type in the first category and  * map it onto a second category (of still types).  */ trait TypeFunctor {  /** This type constructor is used to map any type from the initial category (of all possible types) into another category    * (that may or may not consist of all types).   * @tparam X  The type to be mapped into the new category    * @return  The type in the second category.   */   type F[X]  /**   *  This method takes  a type morphism (an arrow between points A and B in the initial category.      *  Note: A morphism in types is a function that can convert elements of type A into type B).   *  The type morphism is mapped it into the new category defined by the functor.    *  defined by this functor.   *   *  @tparam A  The initial type of the input morphism.    *  @tparam B  The final type of the input morphism   *  @param f  The morphism (function) that can map elements of type A into type B    *  @returns  A morphism that can take values in the mapped category of this functor.   */   def map[A, B](f: A => B): F[A] => F[B]}
NOW, I've given *descriptions* to my abstract types.   Now when people see "A" and "B" in the context of the class, there's a bit of meaning attached to the names, which are accurate.   When I use "F[?]" in later code, I've defined what F is in my source code, so users can understand it.
Scalaz is the *most* disappointing library in the scala ecosystem due to it's lack of documentation and poor naming choice.  If you wish others to understand an abstract concept, you need to provide a description for that concept.   Until you do so, it's just meaningless gibberish.  Scalaz *still* suffers from this, despite good efforts from some.  Claiming that abstract concepts are "lessened' through good names and documentation is bunk, bogus and disappointing to find.
One *could* argue that the source code is the description used for the name.  I could use this excuse to have horrible names throughout my codebase, even if a well known name was available and would help ease someone's ability to learn the concepts in my library.   I don't buy it.
So, as in all things, *naming* is difficult.   A poor name can convey the *wrong* meaning.   However, conveying *no* meaning is perhaps just as poor.   If you're going to use an abstract name (like X or A) for something, please document a description if possible.    If the variable has no meaning to be conveyed, then why is it in your source code?
Even non-english words like "Oooga Booga" convey some meaning.
- Josh


On Sat, Nov 19, 2011 at 4:46 AM, Philippe Lhoste <PhiLho@gmx.net> wrote:

On 18/11/2011 01:57, Kenneth McDonald wrote:

Sorry Tony, but from a software engineering/maintainability point of
view the statement that "type variable names contain no context" is just
as crazy as (and no crazier than) the statement that "program variable
names contain no context". Code is intended to be used in a context, not
matter how general (but as a general point, usually not too general).
Names identify and anchor that context. This is _incredibly_ important
to reusable software.

I have to disagree, at least partially, here. Some software is highly reusable just because they don't have a context...
I barely know Scalaz, mostly from what I have read here and there, but my understanding is that it is very abstract, disconnected from specific domains ("business logic"). Yet people find it very useful, because they mastered the mechanisms it offers, and find them very useful when applied to *their* business logic.
Somehow, it seems like a kind of meta-programming, offering tools to be used in a more specific domain.

I see this kind of tool as highly reusable, yet without identity.
Somehow, it is similar for the collection library.

Of course, you can still name (semi-)abstract stuff, like "the thing we iterate on", "the type of the cumulated result" or such.
Of course, in some domains, the names can draw on the underlying theory: nodes and edges in graph theory, key and values in data maps, and so on. But overall, specific names can get in the way.

Perhaps what is missing from the Scala doc is context. Somehow, it lists together several methods but description is short, context can be missing, etc.

I don't think the tradition of one letter type names will go away, but in a few entries of ScalaDoc I looked at, the types are (succinctly) explained in the Scala doc itself. So even if the names aren't very explicit, the doc is here.

On Thursday 17 November 2011, Kenneth McDonald wrote:
> .... Why not require that every function name be the
> min number of characters to uniquely represent it-- ...

Please show us how to quantify "... the min number of characters
[required] to uniquely represent [every function]."

And tell us how that relates to the concept of functional abstraction.

> Ken

Randall Schulz

Josh, that was... beautiful.
-- Cédric




On Sat, Nov 19, 2011 at 10:33 AM, Josh Suereth <joshua.suereth@gmail.com> wrote:

People ascribe names to abstract things all the time.   When I say "fire", I may be referring to all my experiences of fire as an abstract concept.  Your mind interrupts it and ascribes the aspects of fire that it knows to the words I am using.
The same is true with names.  To Say that the more abstract a thing, the less important the name is BOGUS, bunk.   WHY oh why to we ascribe silly names to abstract concepts like:
Monad MonoidEigenvectorNullspacemonomorphismJacobian
My opinion is that the more abstract a concept, usually the longer or sillier the name (probably because they're named after the person who first *described* the abstract concept).
You see, if I give something a name and a description, I can start using the name in place of the description.   This is what language is all about. 
Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor to me at all.  Again, I can come up with a class Graph where these names make a *lot* of sense.
Even in the case of "def equals(that: Any): Boolean", we still use "that" or "rhs" instead of "x" or "y", Where "that" refers to "something that is not htis" and "rhs" refers to the right-hand-side of an expression.   These words connote *meaning* and only as much meaning as needed to determine what the variable is doing.

trait TypeFunctor {  type F[x]   def map[X, Y](f: X => Y): F[X] => F[Y]}
To those who don't understand the concepts of functors, these names are pretty poor.  However, if I *document* the concepts I'm using.
/** A type functor is a mapping between two categories of types.   A functor can take any type in the first category and  * map it onto a second category (of still types).  */ trait TypeFunctor {  /** This type constructor is used to map any type from the initial category (of all possible types) into another category    * (that may or may not consist of all types).   * @tparam X  The type to be mapped into the new category    * @return  The type in the second category.   */   type F[X]  /**   *  This method takes  a type morphism (an arrow between points A and B in the initial category.      *  Note: A morphism in types is a function that can convert elements of type A into type B).   *  The type morphism is mapped it into the new category defined by the functor.    *  defined by this functor.   *   *  @tparam A  The initial type of the input morphism.    *  @tparam B  The final type of the input morphism   *  @param f  The morphism (function) that can map elements of type A into type B    *  @returns  A morphism that can take values in the mapped category of this functor.   */   def map[A, B](f: A => B): F[A] => F[B]}
NOW, I've given *descriptions* to my abstract types.   Now when people see "A" and "B" in the context of the class, there's a bit of meaning attached to the names, which are accurate.   When I use "F[?]" in later code, I've defined what F is in my source code, so users can understand it.
Scalaz is the *most* disappointing library in the scala ecosystem due to it's lack of documentation and poor naming choice.  If you wish others to understand an abstract concept, you need to provide a description for that concept.   Until you do so, it's just meaningless gibberish.  Scalaz *still* suffers from this, despite good efforts from some.  Claiming that abstract concepts are "lessened' through good names and documentation is bunk, bogus and disappointing to find.
One *could* argue that the source code is the description used for the name.  I could use this excuse to have horrible names throughout my codebase, even if a well known name was available and would help ease someone's ability to learn the concepts in my library.   I don't buy it.
So, as in all things, *naming* is difficult.   A poor name can convey the *wrong* meaning.   However, conveying *no* meaning is perhaps just as poor.   If you're going to use an abstract name (like X or A) for something, please document a description if possible.    If the variable has no meaning to be conveyed, then why is it in your source code?
Even non-english words like "Oooga Booga" convey some meaning.
- Josh


On Sat, Nov 19, 2011 at 4:46 AM, Philippe Lhoste <PhiLho@gmx.net> wrote:

On 18/11/2011 01:57, Kenneth McDonald wrote:

Sorry Tony, but from a software engineering/maintainability point of
view the statement that "type variable names contain no context" is just
as crazy as (and no crazier than) the statement that "program variable
names contain no context". Code is intended to be used in a context, not
matter how general (but as a general point, usually not too general).
Names identify and anchor that context. This is _incredibly_ important
to reusable software.

I have to disagree, at least partially, here. Some software is highly reusable just because they don't have a context...
I barely know Scalaz, mostly from what I have read here and there, but my understanding is that it is very abstract, disconnected from specific domains ("business logic"). Yet people find it very useful, because they mastered the mechanisms it offers, and find them very useful when applied to *their* business logic.
Somehow, it seems like a kind of meta-programming, offering tools to be used in a more specific domain.

I see this kind of tool as highly reusable, yet without identity.
Somehow, it is similar for the collection library.

Of course, you can still name (semi-)abstract stuff, like "the thing we iterate on", "the type of the cumulated result" or such.
Of course, in some domains, the names can draw on the underlying theory: nodes and edges in graph theory, key and values in data maps, and so on. But overall, specific names can get in the way.

Perhaps what is missing from the Scala doc is context. Somehow, it lists together several methods but description is short, context can be missing, etc.

I don't think the tradition of one letter type names will go away, but in a few entries of ScalaDoc I looked at, the types are (succinctly) explained in the Scala doc itself. So even if the names aren't very explicit, the doc is here.

I was assuming that the number of functions are known (or at least bounded), in which case the calculation is trivial.
The observation was intended semiseriously...why represent _anything_ with a number of characters greater than that necessary to guarantee a unique representation? Obviously, because further characters can add (for lack of a better term) meta-semantic meaning.
Ken

On Saturday, November 19, 2011 3:19:14 PM UTC-6, Randall Schulz wrote:

On Thursday 17 November 2011, Kenneth McDonald wrote:
> .... Why not require that every function name be the
> min number of characters to uniquely represent it-- ...

Please show us how to quantify "... the min number of characters
[required] to uniquely represent [every function]."

And tell us how that relates to the concept of functional abstraction.

> Ken

Randall Schulz

I have no referral to the referred-to article. Nonetheless I will put myself out on a limb: Prefixing interfaces with I is perfectly valid if the mental payback is greater than the cost. As (I believe) it is in Java, but (for obvious reasons) is not in Scala.
Ken

OK, if you're willing to go with Map[K, V], why not Map[Key, Value]. _Vastly_ more descriptive, not much longer, much more helpful to the newcomer, not any signficant drawback to the experienced.
Ken

Looked it up. Simply an entry in the Scaladoc docs, and I don't see that is has any relevance to the current discussion.
Ken

On Saturday 19 November 2011, Kenneth McDonald wrote:
> I was assuming that the number of functions are known (or at least
> bounded), in which case the calculation is trivial.

I believe there are aleph_0 distinct discrete functions. Probably
aleph_1 distinct functions over continuous variables. Those are just
guesses, though...

> The observation was intended semiseriously...why represent _anything_
> with a number of characters greater than that necessary to guarantee
> a unique representation? Obviously, because further characters can
> add (for lack of a better term) meta-semantic meaning.

I did not detect the (implied) semi-humor. Sorry...

I don't know what "meta-semantic meaning" might be, but humans do
clearly benefit greatly from whatever connotative value they can derive
from the particular choice of symbols even though those symbols are, in
fact, entirely arbitrary.

> Ken

Randall Schulz

> On Saturday, November 19, 2011 3:19:14 PM UTC-6, Randall Schulz wrote:
> > On Thursday 17 November 2011, Kenneth McDonald wrote:
> > > .... Why not require that every function name be the
> > > min number of characters to uniquely represent it-- ...
> >
> > Please show us how to quantify "... the min number of characters
> > [required] to uniquely represent [every function]."
> >
> > And tell us how that relates to the concept of functional
> > abstraction.
> >
> > > Ken
> >
> > Randall Schulz

The Map data structure is intrinsically associated with the concept of a data structure that represents some key instances drawn from a key set conforming to a Key type that 'map to' some value instances drawn from a value set/bag conforming to a Value type. If a person doesn't understand Key/Value (or K/V) because they don't know what a Map is, then they need to find out what a Map is. The issue you're raising in this case isn't with the naming of the type parameters, but that the entire concept modelled by the Map isn't known to the user. Once they understand the Map abstraction, it's much easer for a normal programmer to look at signatures with the type parameters Key/Value (or K/V) than A/B and associate this back to the Map abstraction. Normal people find names and mnemonics easier to remember than random letters. We can find any amount of published literature that demonstrates this experimentally, and probably also papers that specifically dissect out what sub-population this doesn't hold for (hint - this sub-population is not over-represented in that which is also your average programmer, certainly not to the point that you can discard using informative names in APIs aimed at average programmers).

Again, I disagree. At some point I may have to look it up, but basically, it takes no more cognitive processing to understand "Value" as "Value" than it does to understand "V" as "Value". Probably even less. Whereas if you insist on using V as Value, where does that leave the poor graph programmer who would like to use V as Vertex?
The assumption that _your_ domains and ranges should command single-char status is false and harmful.
Ken 

Yes, because a very straight-forward and efficient answer is totally

off-the-charts.

As usual from you, you are spouting complete nonsense. If I were in such an interview, I would assume that my interviewer wanted to test my understanding of basic data structures. (Your assumption seems to be that the interviewer's expectations are spread out across the Milky way). I would then return an answer consonant with these expectations, and be willing to answer further questions on the same topic if the interviewer wanted.
Tony, don't you freakin' get it? You are brilliant (good) but virtually incapable of communicating with the rest of humanity who is below your level of brilliance. (This is bad. Don't ask me to go into why, if you don't understand it, even a brain transplant won't help). As long as you maintain your pretense of "superiority" over the rest of us, you will achieve almost nothing. If you come to understand that the rest of us do not do things the way you do and never will, then you have a chance to make a real contribution.
Just feedback from someone who would really like to read reasonable tract from you, but has never found one.
Ken

On Thursday, November 17, 2011 10:55:59 PM UTC-6, Josh Suereth wrote:

Guys,  it seems The utility of this discussion has declined.   Let's refrain from bloodying noses by continuing in the current vein.

I'll throw something out there.

Type parameters *are parameters *  just like method parameters.   If you think method parameters require a certain naming style, it is probably worthwhile to use this on type parameters.

If a type parameter looks like a class/type, that's similar to a method parameter looking like a member / term.   Notice the adjustments to the unofficial style guide for this.

Could you throw out a ref to the unofficial style guide?
Ken 

You've got to pull your head out of your rear-end if you'd like to have a chat. You know, clue up, come to terms with the fact that "you're just crazy" is not an acceptable argument, while lecturing others on communication skills. By the way, that looks really dumb y'know? Having no clue on the subject matter, vomiting incoherent arguments, proclaiming your victory all the while thinking you are somehow qualified to lecture on communication skills.

Let me know when you are ready to work toward a coherent and aspirational goal, whatever it might be; the subject matter at hand or not. I'm serious; until then, you have nothing interesting to offer. Don't take it personally. I lament harder than you do, promise.

Just let me know when.

On Nov 20, 2011 11:20 AM, "Kenneth McDonald" <ykkenmcd@gmail.com> wrote:

Yes, because a very straight-forward and efficient answer is totally

off-the-charts.

As usual from you, you are spouting complete nonsense. If I were in such an interview, I would assume that my interviewer wanted to test my understanding of basic data structures. (Your assumption seems to be that the interviewer's expectations are spread out across the Milky way). I would then return an answer consonant with these expectations, and be willing to answer further questions on the same topic if the interviewer wanted.
Tony, don't you freakin' get it? You are brilliant (good) but virtually incapable of communicating with the rest of humanity who is below your level of brilliance. (This is bad. Don't ask me to go into why, if you don't understand it, even a brain transplant won't help). As long as you maintain your pretense of "superiority" over the rest of us, you will achieve almost nothing. If you come to understand that the rest of us do not do things the way you do and never will, then you have a chance to make a real contribution.
Just feedback from someone who would really like to read reasonable tract from you, but has never found one.
Ken

> Could you throw out a ref to the unofficial style guide?
It seems that most up-to-date lives now here: http://docs.scala-lang.org/style/

On Sat, Nov 19, 2011 at 5:31 PM, Kenneth McDonald <ykkenmcd@gmail.com> wrote:

On Thursday, November 17, 2011 10:55:59 PM UTC-6, Josh Suereth wrote:

Guys,  it seems The utility of this discussion has declined.   Let's refrain from bloodying noses by continuing in the current vein.

I'll throw something out there.

Type parameters *are parameters *  just like method parameters.   If you think method parameters require a certain naming style, it is probably worthwhile to use this on type parameters.

If a type parameter looks like a class/type, that's similar to a method parameter looking like a member / term.   Notice the adjustments to the unofficial style guide for this.

Could you throw out a ref to the unofficial style guide?
Ken 

Ken,

The funniest - and saddest - thing in all of this is that Tony is
trying very hard to dissuade you of the opinion that he is so
brilliant!

When I started with FP a few years ago I felt the same as you do now.
It seemed complex. Guys like Tony seemed uber smart and I thought I
could never learn as much as they had. But then I started learning
the basic concepts, and the concepts that build on those, and so on.
I realized just how wrong I was. Tony is a smart dude, maybe smarter
than I am maybe not. But he's certainly been around the FP block
longer than I, and most other people, have been. So he's learned -
really learned, not just glossed over the concepts like some people do
- about FP and the concepts involved. As I've seen him say in various
other threads like this, it's not like he was born with this
knowledge.

You are hurting yourself - and I wish it was only yourself, but more
on that in a second - by continuing to say, "Tony is so much smarter
than me and everybody else, we can't possible ever understand all this
stuff. It's too complex!" In fact, it's not complex at all. It only
looks that way to someone new to the concepts, much like calculus,
linear algebra and differential equations look complex to someone just
learning basic algebra. But these are things that _everyone_ can come
to understand given time and effort.

If you don't want to put in the time and effort to learn these things,
then fine. But stop raising everyone who has taken the time and put
in the effort up on a pedestal - yes, you are the one putting them
there, they are not putting themselves there - and using that as an
excuse for you not understanding! You do them a disservice by saying
that's it is some natural born gift that allows them to understand
these things and - to retract what I said earlier - you perpetuate the
myth to others, causing them to be scared away by these concepts!
(When I was learning about monads the biggest thing I had to overcome
was all the hype around them. I understood the basics pretty quickly,
but thought I was missing something because of all the blogs and
people talking about how hard monads are to understand. But they are
the simplest things possible!)

So please, please stop with this, "It's so complex and your so smart I
can't possibly hope to understand this stuff the way you do,"
nonsense.

On Sat, Nov 19, 2011 at 6:20 PM, Kenneth McDonald wrote:
>
> Yes, because a very straight-forward and efficient answer is totally
>>
>> off-the-charts.
>
> As usual from you, you are spouting complete nonsense. If I were in such an
> interview, I would assume that my interviewer wanted to test my
> understanding of basic data structures. (Your assumption seems to be that
> the interviewer's expectations are spread out across the Milky way). I would
> then return an answer consonant with these expectations, and be willing to
> answer further questions on the same topic if the interviewer wanted.
> Tony, don't you freakin' get it? You are brilliant (good) but virtually
> incapable of communicating with the rest of humanity who is below your level
> of brilliance. (This is bad. Don't ask me to go into why, if you don't
> understand it, even a brain transplant won't help). As long as you maintain
> your pretense of "superiority" over the rest of us, you will achieve almost
> nothing. If you come to understand that the rest of us do not do things the
> way you do and never will, then you have a chance to make a real
> contribution.
> Just feedback from someone who would really like to read reasonable tract
> from you, but has never found one.
> Ken

On Sat, Nov 19, 2011 at 10:33 AM, Josh Suereth <joshua.suereth@gmail.com> wrote:

trait TypeFunctor {  type F[x]   def map[X, Y](f: X => Y): F[X] => F[Y] }
> To those who don't understand the concepts of functors, these names are pretty poor.  However, if I *document* the concepts I'm using.
You don't have to understand the concepts of functors to see it, you just need to be familiar with some parts of Scala language - abstract types, type constructors, in-place function type definition with =>.
Then it's obvious that F is abstract type with one parameter, and map is a function that takes a function from X to Y and returns a function from F[X] to F[Y].
What is the best meaningful name for a type that all you know about is that it's an argument type of some unspecified function?  One-letter names seem appropriate here, as in lots of other similar contexts.
Your documented version seems actually worse to me - it repeats the same things over and over again, and obscures things by using category theory terminology (Don't get me started on category theory :)

>  If the variable has no meaning to be conveyed, then why is it in your source code?
Type-level source code is a little bit different. Unconstrained type variable is just a wildcard, if you take it to extreme it's just a de Brujin index - it's meaning is determined by the place it occupies in the expression, and nothing more. (but I digress again).

> Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor to me at all.  Again, I can come up with a class Graph where these names make a *lot* of sense.
That one - Graph[NodeData, VertexData] indeed makes sense. Unlike all other graph examples, it's clear that NodeData and VertexData is just a payload attached to nodes and edges. 

People ascribe names to abstract things all the time.   When I say "fire", I may be referring to all my experiences of fire as an abstract concept.  Your mind interrupts it and ascribes the aspects of fire that it knows to the words I am using.
The same is true with names.  To Say that the more abstract a thing, the less important the name is BOGUS, bunk.   WHY oh why to we ascribe silly names to abstract concepts like:
Monad MonoidEigenvectorNullspacemonomorphismJacobian
My opinion is that the more abstract a concept, usually the longer or sillier the name (probably because they're named after the person who first *described* the abstract concept).
You see, if I give something a name and a description, I can start using the name in place of the description.   This is what language is all about. 
Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor to me at all.  Again, I can come up with a class Graph where these names make a *lot* of sense.
Even in the case of "def equals(that: Any): Boolean", we still use "that" or "rhs" instead of "x" or "y", Where "that" refers to "something that is not htis" and "rhs" refers to the right-hand-side of an expression.   These words connote *meaning* and only as much meaning as needed to determine what the variable is doing.

trait TypeFunctor {  type F[x]   def map[X, Y](f: X => Y): F[X] => F[Y]}
To those who don't understand the concepts of functors, these names are pretty poor.  However, if I *document* the concepts I'm using.
/** A type functor is a mapping between two categories of types.   A functor can take any type in the first category and  * map it onto a second category (of still types).  */ trait TypeFunctor {  /** This type constructor is used to map any type from the initial category (of all possible types) into another category    * (that may or may not consist of all types).   * @tparam X  The type to be mapped into the new category    * @return  The type in the second category.   */   type F[X]  /**   *  This method takes  a type morphism (an arrow between points A and B in the initial category.      *  Note: A morphism in types is a function that can convert elements of type A into type B).   *  The type morphism is mapped it into the new category defined by the functor.    *  defined by this functor.   *   *  @tparam A  The initial type of the input morphism.    *  @tparam B  The final type of the input morphism   *  @param f  The morphism (function) that can map elements of type A into type B    *  @returns  A morphism that can take values in the mapped category of this functor.   */   def map[A, B](f: A => B): F[A] => F[B]}
NOW, I've given *descriptions* to my abstract types.   Now when people see "A" and "B" in the context of the class, there's a bit of meaning attached to the names, which are accurate.   When I use "F[?]" in later code, I've defined what F is in my source code, so users can understand it.
Scalaz is the *most* disappointing library in the scala ecosystem due to it's lack of documentation and poor naming choice.  If you wish others to understand an abstract concept, you need to provide a description for that concept.   Until you do so, it's just meaningless gibberish.  Scalaz *still* suffers from this, despite good efforts from some.  Claiming that abstract concepts are "lessened' through good names and documentation is bunk, bogus and disappointing to find.
One *could* argue that the source code is the description used for the name.  I could use this excuse to have horrible names throughout my codebase, even if a well known name was available and would help ease someone's ability to learn the concepts in my library.   I don't buy it.
So, as in all things, *naming* is difficult.   A poor name can convey the *wrong* meaning.   However, conveying *no* meaning is perhaps just as poor.   If you're going to use an abstract name (like X or A) for something, please document a description if possible.    If the variable has no meaning to be conveyed, then why is it in your source code?
Even non-english words like "Oooga Booga" convey some meaning.
- Josh


On Sat, Nov 19, 2011 at 4:46 AM, Philippe Lhoste <PhiLho@gmx.net> wrote:

On 18/11/2011 01:57, Kenneth McDonald wrote:

Sorry Tony, but from a software engineering/maintainability point of
view the statement that "type variable names contain no context" is just
as crazy as (and no crazier than) the statement that "program variable
names contain no context". Code is intended to be used in a context, not
matter how general (but as a general point, usually not too general).
Names identify and anchor that context. This is _incredibly_ important
to reusable software.

I have to disagree, at least partially, here. Some software is highly reusable just because they don't have a context...
I barely know Scalaz, mostly from what I have read here and there, but my understanding is that it is very abstract, disconnected from specific domains ("business logic"). Yet people find it very useful, because they mastered the mechanisms it offers, and find them very useful when applied to *their* business logic.
Somehow, it seems like a kind of meta-programming, offering tools to be used in a more specific domain.

I see this kind of tool as highly reusable, yet without identity.
Somehow, it is similar for the collection library.

Of course, you can still name (semi-)abstract stuff, like "the thing we iterate on", "the type of the cumulated result" or such.
Of course, in some domains, the names can draw on the underlying theory: nodes and edges in graph theory, key and values in data maps, and so on. But overall, specific names can get in the way.

Perhaps what is missing from the Scala doc is context. Somehow, it lists together several methods but description is short, context can be missing, etc.

I don't think the tradition of one letter type names will go away, but in a few entries of ScalaDoc I looked at, the types are (succinctly) explained in the Scala doc itself. So even if the names aren't very explicit, the doc is here.

On Sat, Nov 19, 2011 at 11:33 AM, Josh Suereth wrote:
> People ascribe names to abstract things all the time.   When I say "fire", I
> may be referring to all my experiences of fire as an abstract concept.  Your
> mind interrupts it and ascribes the aspects of fire that it knows to the
> words I am using.
> The same is true with names.  To Say that the more abstract a thing, the
> less important the name is BOGUS, bunk.   WHY oh why to we ascribe silly
> names to abstract concepts like:
> Monad
> Monoid
> Eigenvector
> Nullspace
> monomorphism
> Jacobian
> My opinion is that the more abstract a concept, usually the longer or
> sillier the name (probably because they're named after the person who first
> *described* the abstract concept).
> You see, if I give something a name and a description, I can start using the
> name in place of the description.   This is what language is all about.
> Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor to
> me at all.  Again, I can come up with a class Graph where these names make a
> *lot* of sense.
> Even in the case of "def equals(that: Any): Boolean", we still use "that" or
> "rhs" instead of "x" or "y", Where "that" refers to "something that is not
> htis" and "rhs" refers to the right-hand-side of an expression.   These
> words connote *meaning* and only as much meaning as needed to determine what
> the variable is doing.
>
> trait TypeFunctor {
>   type F[x]
>   def map[X, Y](f: X => Y): F[X] => F[Y]
> }
> To those who don't understand the concepts of functors, these names are
> pretty poor.  However, if I *document* the concepts I'm using.
> /** A type functor is a mapping between two categories of types.   A functor
> can take any type in the first category and
>  * map it onto a second category (of still types).
>  */
> trait TypeFunctor {
>   /** This type constructor is used to map any type from the initial
> category (of all possible types) into another category
>    * (that may or may not consist of all types).
>    * @tparam X  The type to be mapped into the new category
>    * @return  The type in the second category.
>    */
>   type F[X]
>   /**
>    *  This method takes  a type morphism (an arrow between points A and B in
> the initial category.
>    *  Note: A morphism in types is a function that can convert elements of
> type A into type B).
>    *  The type morphism is mapped it into the new category defined by the
> functor.
>    *  defined by this functor.
>    *
>    *  @tparam A  The initial type of the input morphism.
>    *  @tparam B  The final type of the input morphism
>    *  @param f  The morphism (function) that can map elements of type A into
> type B
>    *  @returns  A morphism that can take values in the mapped category of
> this functor.
>    */
>   def map[A, B](f: A => B): F[A] => F[B]
> }
> NOW, I've given *descriptions* to my abstract types.   Now when people see
> "A" and "B" in the context of the class, there's a bit of meaning attached
> to the names, which are accurate.   When I use "F[?]" in later code, I've
> defined what F is in my source code, so users can understand it.
> Scalaz is the *most* disappointing library in the scala ecosystem due to
> it's lack of documentation and poor naming choice.

That's not really fair, is it? I would say that the most
disappointing library has to be the Scala standard library. When I
started using Scala I couldn't make heads or tails of anything. I had
to read books and blogs to understand what was useful to accomplish
the tasks at hand. There were and still are several places in the
scaladoc where concepts - some only known in the Scala community - are
used in a brief sentence describing a method, but no further
explanation is given. This is pretty piss poor for something at the
very core of the language.

Now I'm sure you and everybody else are getting ready to hit the reply
button to tell me all about the great strides that have been made in
documenting the standard lib. And I agree, it has gotten much better
lately. But that didn't happen until Typesafe was founded and the
focus of the Scala creators and maintainers shifted from making Scala
useful to getting Scala used.

Scalaz's creators and maintainers are currently more focused on making
something useful rather than something that is widely used. There is
a ton of documentation in Scalaz - it's all in the types! - and there
is voluminous amounts of pdfs and blogs about the underlying concepts.
No, that documentation has not been *copied* into the source code.
That has not been a focus. It is expected that people interested
enough in learning will Google the concept or ask on the mailing list.
But if you, or anyone else, wants to improve the situation submit a
pull request. As long as descriptions are accurate, they'll be
accepted.

Rich

> If you wish others to
> understand an abstract concept, you need to provide a description for that
> concept.   Until you do so, it's just meaningless gibberish.  Scalaz *still*
> suffers from this, despite good efforts from some.  Claiming that abstract
> concepts are "lessened' through good names and documentation is bunk, bogus
> and disappointing to find.
> One *could* argue that the source code is the description used for the name.
>  I could use this excuse to have horrible names throughout my codebase, even
> if a well known name was available and would help ease someone's ability to
> learn the concepts in my library.   I don't buy it.
> So, as in all things, *naming* is difficult.   A poor name can convey the
> *wrong* meaning.   However, conveying *no* meaning is perhaps just as poor.
>   If you're going to use an abstract name (like X or A) for something,
> please document a description if possible.    If the variable has no meaning
> to be conveyed, then why is it in your source code?
> Even non-english words like "Oooga Booga" convey some meaning.
> - Josh
>
>
> On Sat, Nov 19, 2011 at 4:46 AM, Philippe Lhoste wrote:
>>
>> On 18/11/2011 01:57, Kenneth McDonald wrote:
>>>
>>> Sorry Tony, but from a software engineering/maintainability point of
>>> view the statement that "type variable names contain no context" is just
>>> as crazy as (and no crazier than) the statement that "program variable
>>> names contain no context". Code is intended to be used in a context, not
>>> matter how general (but as a general point, usually not too general).
>>> Names identify and anchor that context. This is _incredibly_ important
>>> to reusable software.
>>
>> I have to disagree, at least partially, here. Some software is highly
>> reusable just because they don't have a context...
>> I barely know Scalaz, mostly from what I have read here and there, but my
>> understanding is that it is very abstract, disconnected from specific
>> domains ("business logic"). Yet people find it very useful, because they
>> mastered the mechanisms it offers, and find them very useful when applied to
>> *their* business logic.
>> Somehow, it seems like a kind of meta-programming, offering tools to be
>> used in a more specific domain.
>>
>> I see this kind of tool as highly reusable, yet without identity.
>> Somehow, it is similar for the collection library.
>>
>> Of course, you can still name (semi-)abstract stuff, like "the thing we
>> iterate on", "the type of the cumulated result" or such.
>> Of course, in some domains, the names can draw on the underlying theory:
>> nodes and edges in graph theory, key and values in data maps, and so on. But
>> overall, specific names can get in the way.
>>
>> Perhaps what is missing from the Scala doc is context. Somehow, it lists
>> together several methods but description is short, context can be missing,
>> etc.
>>
>> I don't think the tradition of one letter type names will go away, but in
>> a few entries of ScalaDoc I looked at, the types are (succinctly) explained
>> in the Scala doc itself. So even if the names aren't very explicit, the doc
>> is here.
>>
>> --
>> Philippe Lhoste

So well put Richard.

The amount of damage that is done by perpetuating the myth that understanding the subject matter at hand is somehow unapproachable by speaking to all these logical fallacies is just sad. No I really want born with categorytheory.so in my brain our whatever nonsense it may require to continue justifying these myths (they astound me every time, so please excuse my naive guessing).

Fine, don't understand it, fine call me names, call me crazy or lacking communication skills, use all the fallacies at your disposal. I DO NOT GIVE A FUCK THAT YOU ARE WRONG AND I REFUSE TO TAKE YOUR BULLYING PERSONALLY.  But I do care that the next guy might fall for it. Thankfully Richard is not one of those and has taught me a few things on occasion and will likely continue to do so (thanks Richard).

To others, beware of the trap, especially the illusion of comfort it advertises. It's bullshit.

On Nov 20, 2011 12:27 PM, "Richard Wallace" <rwallace@thewallacepack.net> wrote:

Ken,

The funniest - and saddest - thing in all of this is that Tony is
trying very hard to dissuade you of the opinion that he is so
brilliant!

When I started with FP a few years ago I felt the same as you do now.
It seemed complex.  Guys like Tony seemed uber smart and I thought I
could never learn as much as they had.  But then I started learning
the basic concepts, and the concepts that build on those, and so on.
I realized just how wrong I was. Tony is a smart dude, maybe smarter
than I am maybe not.  But he's certainly been around the FP block
longer than I, and most other people, have been. So he's learned -
really learned, not just glossed over the concepts like some people do
- about FP and the concepts involved.  As I've seen him say in various
other threads like this, it's not like he was born with this
knowledge.

You are hurting yourself - and I wish it was only yourself, but more
on that in a second - by continuing to say, "Tony is so much smarter
than me and everybody else, we can't possible ever understand all this
stuff.  It's too complex!"  In fact, it's not complex at all.  It only
looks that way to someone new to the concepts, much like calculus,
linear algebra and differential equations look complex to someone just
learning basic algebra.  But these are things that _everyone_ can come
to understand given time and effort.

If you don't want to put in the time and effort to learn these things,
then fine.  But stop raising everyone who has taken the time and put
in the effort up on a pedestal - yes, you are the one putting them
there, they are not putting themselves there - and using that as an
excuse for you not understanding!  You do them a disservice by saying
that's it is some natural born gift that allows them to understand
these things and - to retract what I said earlier - you perpetuate the
myth to others, causing them to be scared away by these concepts!
(When I was learning about monads the biggest thing I had to overcome
was all the hype around them.  I understood the basics pretty quickly,
but thought I was missing something because of all the blogs and
people talking about how hard monads are to understand.  But they are
the simplest things possible!)

So please, please stop with this, "It's so complex and your so smart I
can't possibly hope to understand this stuff the way you do,"
nonsense.

On Sat, Nov 19, 2011 at 6:20 PM, Kenneth McDonald <ykkenmcd@gmail.com> wrote:
>
> Yes, because a very straight-forward and efficient answer is totally
>>
>> off-the-charts.
>
> As usual from you, you are spouting complete nonsense. If I were in such an
> interview, I would assume that my interviewer wanted to test my
> understanding of basic data structures. (Your assumption seems to be that
> the interviewer's expectations are spread out across the Milky way). I would
> then return an answer consonant with these expectations, and be willing to
> answer further questions on the same topic if the interviewer wanted.
> Tony, don't you freakin' get it? You are brilliant (good) but virtually
> incapable of communicating with the rest of humanity who is below your level
> of brilliance. (This is bad. Don't ask me to go into why, if you don't
> understand it, even a brain transplant won't help). As long as you maintain
> your pretense of "superiority" over the rest of us, you will achieve almost
> nothing. If you come to understand that the rest of us do not do things the
> way you do and never will, then you have a chance to make a real
> contribution.
> Just feedback from someone who would really like to read reasonable tract
> from you, but has never found one.
> Ken

This question has no doubt been asked and answered a hundred times, but which online Scala FP or Scalaz tutorial do you recommend? I'm looking for something that is (1) freely available online, (2) starts more or less with the basics of FP and goes from there (3) provides examples in Scala. Thanks.

(Yes, I did a quick google on it, but the results do not appear to be particularly useful to me.)

--Russ P.


On Sat, Nov 19, 2011 at 7:05 PM, Tony Morris <tmorris@tmorris.net> wrote:

So well put Richard.

The amount of damage that is done by perpetuating the myth that understanding the subject matter at hand is somehow unapproachable by speaking to all these logical fallacies is just sad. No I really want born with categorytheory.so in my brain our whatever nonsense it may require to continue justifying these myths (they astound me every time, so please excuse my naive guessing).

Fine, don't understand it, fine call me names, call me crazy or lacking communication skills, use all the fallacies at your disposal. I DO NOT GIVE A FUCK THAT YOU ARE WRONG AND I REFUSE TO TAKE YOUR BULLYING PERSONALLY.  But I do care that the next guy might fall for it. Thankfully Richard is not one of those and has taught me a few things on occasion and will likely continue to do so (thanks Richard).

To others, beware of the trap, especially the illusion of comfort it advertises. It's bullshit.

On Nov 20, 2011 12:27 PM, "Richard Wallace" <rwallace@thewallacepack.net> wrote:

Ken,

The funniest - and saddest - thing in all of this is that Tony is
trying very hard to dissuade you of the opinion that he is so
brilliant!

When I started with FP a few years ago I felt the same as you do now.
It seemed complex.  Guys like Tony seemed uber smart and I thought I
could never learn as much as they had.  But then I started learning
the basic concepts, and the concepts that build on those, and so on.
I realized just how wrong I was. Tony is a smart dude, maybe smarter
than I am maybe not.  But he's certainly been around the FP block
longer than I, and most other people, have been. So he's learned -
really learned, not just glossed over the concepts like some people do
- about FP and the concepts involved.  As I've seen him say in various
other threads like this, it's not like he was born with this
knowledge.

You are hurting yourself - and I wish it was only yourself, but more
on that in a second - by continuing to say, "Tony is so much smarter
than me and everybody else, we can't possible ever understand all this
stuff.  It's too complex!"  In fact, it's not complex at all.  It only
looks that way to someone new to the concepts, much like calculus,
linear algebra and differential equations look complex to someone just
learning basic algebra.  But these are things that _everyone_ can come
to understand given time and effort.

If you don't want to put in the time and effort to learn these things,
then fine.  But stop raising everyone who has taken the time and put
in the effort up on a pedestal - yes, you are the one putting them
there, they are not putting themselves there - and using that as an
excuse for you not understanding!  You do them a disservice by saying
that's it is some natural born gift that allows them to understand
these things and - to retract what I said earlier - you perpetuate the
myth to others, causing them to be scared away by these concepts!
(When I was learning about monads the biggest thing I had to overcome
was all the hype around them.  I understood the basics pretty quickly,
but thought I was missing something because of all the blogs and
people talking about how hard monads are to understand.  But they are
the simplest things possible!)

So please, please stop with this, "It's so complex and your so smart I
can't possibly hope to understand this stuff the way you do,"
nonsense.

On Sat, Nov 19, 2011 at 6:20 PM, Kenneth McDonald <ykkenmcd@gmail.com> wrote:
>
> Yes, because a very straight-forward and efficient answer is totally
>>
>> off-the-charts.
>
> As usual from you, you are spouting complete nonsense. If I were in such an
> interview, I would assume that my interviewer wanted to test my
> understanding of basic data structures. (Your assumption seems to be that
> the interviewer's expectations are spread out across the Milky way). I would
> then return an answer consonant with these expectations, and be willing to
> answer further questions on the same topic if the interviewer wanted.
> Tony, don't you freakin' get it? You are brilliant (good) but virtually
> incapable of communicating with the rest of humanity who is below your level
> of brilliance. (This is bad. Don't ask me to go into why, if you don't
> understand it, even a brain transplant won't help). As long as you maintain
> your pretense of "superiority" over the rest of us, you will achieve almost
> nothing. If you come to understand that the rest of us do not do things the
> way you do and never will, then you have a chance to make a real
> contribution.
> Just feedback from someone who would really like to read reasonable tract
> from you, but has never found one.
> Ken

--
http://RussP.us

Applause!

Well said H[J,S] ;-)

Cheers, Eric


On 2011-11-19 10:33 AM, Josh Suereth wrote:

NsjVihVBDnypYuk-pD8R_P43Fm+s4-2A [at] mail [dot] gmail [dot] com" type="cite">People ascribe names to abstract things all the time.   When I say "fire", I may be referring to all my experiences of fire as an abstract concept.  Your mind interrupts it and ascribes the aspects of fire that it knows to the words I am using.
The same is true with names.  To Say that the more abstract a thing, the less important the name is BOGUS, bunk.   WHY oh why to we ascribe silly names to abstract concepts like:
Monad Monoid Eigenvector Nullspace monomorphism Jacobian
My opinion is that the more abstract a concept, usually the longer or sillier the name (probably because they're named after the person who first *described* the abstract concept).
You see, if I give something a name and a description, I can start using the name in place of the description.   This is what language is all about. 
Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor to me at all.  Again, I can come up with a class Graph where these names make a *lot* of sense.
Even in the case of "def equals(that: Any): Boolean", we still use "that" or "rhs" instead of "x" or "y", Where "that" refers to "something that is not htis" and "rhs" refers to the right-hand-side of an expression.   These words connote *meaning* and only as much meaning as needed to determine what the variable is doing.

trait TypeFunctor {   type F[x]   def map[X, Y](f: X => Y): F[X] => F[Y] }
To those who don't understand the concepts of functors, these names are pretty poor.  However, if I *document* the concepts I'm using.
/** A type functor is a mapping between two categories of types.   A functor can take any type in the first category and  * map it onto a second category (of still types).   */ trait TypeFunctor {   /** This type constructor is used to map any type from the initial category (of all possible types) into another category    * (that may or may not consist of all types).    * @tparam X  The type to be mapped into the new category    * @return  The type in the second category.    */   type F[X]   /**    *  This method takes  a type morphism (an arrow between points A and B in the initial category.      *  Note: A morphism in types is a function that can convert elements of type A into type B).    *  The type morphism is mapped it into the new category defined by the functor.    *  defined by this functor.    *    *  @tparam A  The initial type of the input morphism.    *  @tparam B  The final type of the input morphism    *  @param f  The morphism (function) that can map elements of type A into type B    *  @returns  A morphism that can take values in the mapped category of this functor.    */   def map[A, B](f: A => B): F[A] => F[B] }
NOW, I've given *descriptions* to my abstract types.   Now when people see "A" and "B" in the context of the class, there's a bit of meaning attached to the names, which are accurate.   When I use "F[?]" in later code, I've defined what F is in my source code, so users can understand it.
Scalaz is the *most* disappointing library in the scala ecosystem due to it's lack of documentation and poor naming choice.  If you wish others to understand an abstract concept, you need to provide a description for that concept.   Until you do so, it's just meaningless gibberish.  Scalaz *still* suffers from this, despite good efforts from some.  Claiming that abstract concepts are "lessened' through good names and documentation is bunk, bogus and disappointing to find.
One *could* argue that the source code is the description used for the name.  I could use this excuse to have horrible names throughout my codebase, even if a well known name was available and would help ease someone's ability to learn the concepts in my library.   I don't buy it.
So, as in all things, *naming* is difficult.   A poor name can convey the *wrong* meaning.   However, conveying *no* meaning is perhaps just as poor.   If you're going to use an abstract name (like X or A) for something, please document a description if possible.    If the variable has no meaning to be conveyed, then why is it in your source code?
Even non-english words like "Oooga Booga" convey some meaning.
- Josh


On Sat, Nov 19, 2011 at 4:46 AM, Philippe Lhoste <PhiLho [at] gmx [dot] net" rel="nofollow">PhiLho@gmx.net> wrote:

On 18/11/2011 01:57, Kenneth McDonald wrote:

Sorry Tony, but from a software engineering/maintainability point of
view the statement that "type variable names contain no context" is just
as crazy as (and no crazier than) the statement that "program variable
names contain no context". Code is intended to be used in a context, not
matter how general (but as a general point, usually not too general).
Names identify and anchor that context. This is _incredibly_ important
to reusable software.

I have to disagree, at least partially, here. Some software is highly reusable just because they don't have a context...
I barely know Scalaz, mostly from what I have read here and there, but my understanding is that it is very abstract, disconnected from specific domains ("business logic"). Yet people find it very useful, because they mastered the mechanisms it offers, and find them very useful when applied to *their* business logic.
Somehow, it seems like a kind of meta-programming, offering tools to be used in a more specific domain.

I see this kind of tool as highly reusable, yet without identity.
Somehow, it is similar for the collection library.

Of course, you can still name (semi-)abstract stuff, like "the thing we iterate on", "the type of the cumulated result" or such.
Of course, in some domains, the names can draw on the underlying theory: nodes and edges in graph theory, key and values in data maps, and so on. But overall, specific names can get in the way.

Perhaps what is missing from the Scala doc is context. Somehow, it lists together several methods but description is short, context can be missing, etc.

I don't think the tradition of one letter type names will go away, but in a few entries of ScalaDoc I looked at, the types are (succinctly) explained in the Scala doc itself. So even if the names aren't very explicit, the doc is here.

--
Philippe Lhoste
--  (near) Paris -- France
--  http://Phi.Lho.free.fr
--  --  --  --  --  --  --  --  --  --  --  --  --  --

On Sat, Nov 19, 2011 at 6:47 PM, Richard Wallace
wrote:
> And I agree, it has gotten much better
> lately.  But that didn't happen until Typesafe was founded and the
> focus of the Scala creators and maintainers shifted from making Scala
> useful to getting Scala used.

Post hoc ergo propter hoc.

I can just say here: Sorry, Tony you are wrong. I think I am qualified to say that. I have been in FP much longer than you were. I am a member of the IFIP working group for functional programming, together with people like Peyton Jones, Wadler, Hughes. I am chairing the technical advisory board of Microsoft Research Cambridge which does both Haskell and F#. I am also a fellow of the ACM for my achievements in the area. 
What you do is the hard hard fringe of category theory, largely uninteresting even to the mainstream of FP.  Of course, over the years a number of papers and talks appeared on the subject; none of them got very far.
So, if you want to follow that side show (and a side show it is!) for personal pleasure that's great! But don't assume everybody else needs to follow you; don't even try to convince them. It's detrimental for them and for the success of FP as a whole.
 -- Martin

On 20/11/11 19:15, martin odersky wrote:
> I can just say here: Sorry, Tony you are wrong. I think I am qualified to
> say that. I have been in FP much longer than you were. I am a member of the
> IFIP working group for functional programming, together with people like
> Peyton Jones, Wadler, Hughes. I am chairing the technical advisory board of
> Microsoft Research Cambridge which does both Haskell and F#. I am also a
> fellow of the ACM for my achievements in the area.
>
> What you do is the hard hard fringe of category theory, largely
> uninteresting even to the mainstream of FP. Of course, over the years a
> number of papers and talks appeared on the subject; none of them got very
> far.
>
> So, if you want to follow that side show (and a side show it is!) for
> personal pleasure that's great! But don't assume everybody else needs to
> follow you; don't even try to convince them. It's detrimental for them and
> for the success of FP as a whole.
>

On Sun, Nov 20, 2011 at 10:33 AM, Tony Morris <tonymorris@gmail.com> wrote:

On 20/11/11 19:15, martin odersky wrote:
> I can just say here: Sorry, Tony you are wrong. I think I am qualified to
> say that. I have been in FP much longer than you were. I am a member of the
> IFIP working group for functional programming, together with people like
> Peyton Jones, Wadler, Hughes. I am chairing the technical advisory board of
> Microsoft Research Cambridge which does both Haskell and F#. I am also a
> fellow of the ACM for my achievements in the area.
>
> What you do is the hard hard fringe of category theory, largely
> uninteresting even to the mainstream of FP.  Of course, over the years a
> number of papers and talks appeared on the subject; none of them got very
> far.
>
> So, if you want to follow that side show (and a side show it is!) for
> personal pleasure that's great! But don't assume everybody else needs to
> follow you; don't even try to convince them. It's detrimental for them and
> for the success of FP as a whole.
>
>  -- Martin
>

Martin, I have no idea what you think I am wrong about, but I am pretty
sure you are wrong about what it is I do and I am also pretty sure you
need to look at category theory a bit more so that you can better
understand it. No, I don't do the "hard hard fringe of category theory."
I have no idea where you even got that idea. Did you just make it up?

The credentials are unpersuasive.

--

 I did not intend to convince you with this mail, Tony. I know you can't be convinced. I am trying to convince some of the others that what you say need not be taken as gold, because your position is fringe even in classical FP. I don't have the time like you do to monopolize discussions on scala lists with more than a dozen messages a day. So most likely I will not be able to respond in detail to future messages of yours. I trust you will not construe my silence as endorsement.
I think you would do the scalaz project and the community at large a great favor if you stopped posting on threads that are not directly related to scalaz.

 -- Martin 

I want to "quickly" comment on the whole Scalaz documentation/complexity thing.

Disclaimer: I say this as an (ab)user of Scalaz.

Programming is hard, learning totally new concepts is hard - the payoff has to be worth the investment.  Documentation should provide enough of an overview to answer the "is it worth it" question.

Here Scalaz documentation is poor. It takes way too much time to be able to understand the why's and, perhaps more importantly the how's. The why's I will come back to, but the how's will be solved in large part by Scalaz 7.

7 makes a big shift in code organization, putting most type class instances right with their related type (not spread out over a few files). Scaladoc should then be a usable tool for discovering the how.

The why's on the other hand require a bit of searching - see the deriving presentations and read those scary Runar blog posts, hell you can even read about Elephants if it helps. I believe that the upcoming book might provide the overview that most need.

The important part is this: you will reinvent parts of Scalaz sooner or later. Key parts of your existing code base already do.  Personally I have reinvented:

* Equal
* Validation (badly I might add)
* Iteratees
* Ephemeral stream
* Tree based zippers (although my implementation better fits my needs)

I was for a time also on the verge of reinventing arrows.

Any perceived complexity in Scalaz is due to how general it is and how hard it works around and within the type system to give you those goodies.

I write all this because these last few posts from Ken keep coming back to Scalaz, of course with some help from the ever communactive Tony.

It's a distraction - Scalaz is generally useful, and if you find yourself asking "this fp style thing seems it should be reusable" then look in Scalaz.  If it's not obviously there ask in the Scalaz group, perhaps looking at it slightly differently makes all the difference.

To finish: I personally find it very comforting that, in Scalaz, there is a library that provides a one stop shop for solving many of my abstraction issues. I don't buy into "follow the types" you *do* need easier intros to get going (the internet is full of them) but the payoff *is* worth it - promise. (sorry Tony couldn't resist)

On 20/11/11 19:50, martin odersky wrote:
> On Sun, Nov 20, 2011 at 10:33 AM, Tony Morris wrote:
>
>> On 20/11/11 19:15, martin odersky wrote:
>>> I can just say here: Sorry, Tony you are wrong. I think I am qualified to
>>> say that. I have been in FP much longer than you were. I am a member of
>> the
>>> IFIP working group for functional programming, together with people like
>>> Peyton Jones, Wadler, Hughes. I am chairing the technical advisory board
>> of
>>> Microsoft Research Cambridge which does both Haskell and F#. I am also a
>>> fellow of the ACM for my achievements in the area.
>>>
>>> What you do is the hard hard fringe of category theory, largely
>>> uninteresting even to the mainstream of FP. Of course, over the years a
>>> number of papers and talks appeared on the subject; none of them got very
>>> far.
>>>
>>> So, if you want to follow that side show (and a side show it is!) for
>>> personal pleasure that's great! But don't assume everybody else needs to
>>> follow you; don't even try to convince them. It's detrimental for them
>> and
>>> for the success of FP as a whole.
>>>
>>> -- Martin
>>>
>> Martin, I have no idea what you think I am wrong about, but I am pretty
>> sure you are wrong about what it is I do and I am also pretty sure you
>> need to look at category theory a bit more so that you can better
>> understand it. No, I don't do the "hard hard fringe of category theory."
>> I have no idea where you even got that idea. Did you just make it up?
>>
>> The credentials are unpersuasive.
>>
>> --
>>
> I did not intend to convince you with this mail, Tony. I know you can't be
> convinced. I am trying to convince some of the others that what you say
> need not be taken as gold, because your position is fringe even in
> classical FP. I don't have the time like you do to monopolize discussions
> on scala lists with more than a dozen messages a day. So most likely I will
> not be able to respond in detail to future messages of yours. I trust you
> will not construe my silence as endorsement.
>
> I think you would do the scalaz project and the community at large a great
> favor if you stopped posting on threads that are not directly related to
> scalaz.
>

On 20/11/11 19:58, Chris Twiner wrote:
> I want to "quickly" comment on the whole Scalaz documentation/complexity
> thing.
>
> Disclaimer: I say this as an (ab)user of Scalaz.
>
> Programming is hard, learning totally new concepts is hard - the payoff has
> to be worth the investment. Documentation should provide enough of an
> overview to answer the "is it worth it" question.
>
> Here Scalaz documentation is poor. It takes way too much time to be able to
> understand the why's and, perhaps more importantly the how's. The why's I
> will come back to, but the how's will be solved in large part by Scalaz 7.
>
> 7 makes a big shift in code organization, putting most type class instances
> right with their related type (not spread out over a few files). Scaladoc
> should then be a usable tool for discovering the how.
>
> The why's on the other hand require a bit of searching - see the deriving
> presentations and read those scary Runar blog posts, hell you can even read
> about Elephants if it helps. I believe that the upcoming book might provide
> the overview that most need.
>
> The important part is this: you will reinvent parts of Scalaz sooner or
> later. Key parts of your existing code base already do. Personally I have
> reinvented:
>
> * Equal
> * Validation (badly I might add)
> * Iteratees
> * Ephemeral stream
> * Tree based zippers (although my implementation better fits my needs)
>
> I was for a time also on the verge of reinventing arrows.
>
> Any perceived complexity in Scalaz is due to how general it is and how hard
> it works around and within the type system to give you those goodies.
>
> I write all this because these last few posts from Ken keep coming back to
> Scalaz, of course with some help from the ever communactive Tony.
>
> It's a distraction - Scalaz is generally useful, and if you find yourself
> asking "this fp style thing seems it should be reusable" then look in
> Scalaz. If it's not obviously there ask in the Scalaz group, perhaps
> looking at it slightly differently makes all the difference.
>
> To finish: I personally find it very comforting that, in Scalaz, there is a
> library that provides a one stop shop for solving many of my abstraction
> issues. I don't buy into "follow the types" you *do* need easier intros to
> get going (the internet is full of them) but the payoff *is* worth it -
> promise. (sorry Tony couldn't resist)
>

You're not the first person to accidentally reinvent many concepts in
scalaz. Even Martin did exactly that a couple of weeks ago.

I appreciate your honesty. It should probably go on the scalaz mailing
list though. No need to apologise.

On Sun, Nov 20, 2011 at 11:03 AM, Tony Morris <tonymorris@gmail.com> wrote:

On 20/11/11 19:58, Chris Twiner wrote:
> I want to "quickly" comment on the whole Scalaz documentation/complexity
> thing.
>
> Disclaimer: I say this as an (ab)user of Scalaz.
>
> Programming is hard, learning totally new concepts is hard - the payoff has
> to be worth the investment.  Documentation should provide enough of an
> overview to answer the "is it worth it" question.
>
> Here Scalaz documentation is poor. It takes way too much time to be able to
> understand the why's and, perhaps more importantly the how's. The why's I
> will come back to, but the how's will be solved in large part by Scalaz 7.
>
> 7 makes a big shift in code organization, putting most type class instances
> right with their related type (not spread out over a few files). Scaladoc
> should then be a usable tool for discovering the how.
>
> The why's on the other hand require a bit of searching - see the deriving
> presentations and read those scary Runar blog posts, hell you can even read
> about Elephants if it helps. I believe that the upcoming book might provide
> the overview that most need.
>
> The important part is this: you will reinvent parts of Scalaz sooner or
> later. Key parts of your existing code base already do.  Personally I have
> reinvented:
>
> * Equal
> * Validation (badly I might add)
> * Iteratees
> * Ephemeral stream
> * Tree based zippers (although my implementation better fits my needs)
>
> I was for a time also on the verge of reinventing arrows.
>

 Of course these are useful concepts in scalaz! But the approach that you have to understand it in its entirety is wrong, IMO. And I believe few of the scalaz maintainers would claim that you need to. Also, sometimes it's more enlightening if you _do_ rediscover some of these features yourself than if you are made to swallow the whole tower of abstraction at one go. Makes you more appreciate their usefulness.
A criticism of category theory, which I share, is not that it does not present useful concepts. In a sense category theory is the most general of all theories so of course it will describe a lot of useful concepts. The criticism is that the concepts covered by category theory tend to be very general but are often not very deep*, and the overhead of learning category theory is not paid back by the usefulness of applying it. That's why category theory did not make greater inroads into mathematics and computer science (it was quite fashionable in both branches for a while, at different periods in time).
* By deep, I mean: the _application_ of the concept in a concrete scenario would otherwise require a hard proof (if we talk about mathematics) or very involved code (if we talk about computing).
My favorite here is the Richard Feynman auto-biography, where he talks about Brasilian physics education of the 60s. That education was very abstract and deductive. It presented a bunch of laws which students had to memorize, but could not apply to anything real. Feynman was very critical of this approach, of course. 
So, I believe if scalaz should have wider appeal to people, it will need to stress self-discovery more. Instead of just pushing a library out, develop material how people can discover central abstractions themselves. Another great example how that's done is Structure and Interpretation of Computer Programming by Abelson and Sussman.
Cheers
 -- Martin

On 20/11/11 20:52, martin odersky wrote:
> On Sun, Nov 20, 2011 at 11:03 AM, Tony Morris wrote:
>
>> On 20/11/11 19:58, Chris Twiner wrote:
>>> I want to "quickly" comment on the whole Scalaz documentation/complexity
>>> thing.
>>>
>>> Disclaimer: I say this as an (ab)user of Scalaz.
>>>
>>> Programming is hard, learning totally new concepts is hard - the payoff
>> has
>>> to be worth the investment. Documentation should provide enough of an
>>> overview to answer the "is it worth it" question.
>>>
>>> Here Scalaz documentation is poor. It takes way too much time to be able
>> to
>>> understand the why's and, perhaps more importantly the how's. The why's I
>>> will come back to, but the how's will be solved in large part by Scalaz
>> 7.
>>> 7 makes a big shift in code organization, putting most type class
>> instances
>>> right with their related type (not spread out over a few files). Scaladoc
>>> should then be a usable tool for discovering the how.
>>>
>>> The why's on the other hand require a bit of searching - see the deriving
>>> presentations and read those scary Runar blog posts, hell you can even
>> read
>>> about Elephants if it helps. I believe that the upcoming book might
>> provide
>>> the overview that most need.
>>>
>>> The important part is this: you will reinvent parts of Scalaz sooner or
>>> later. Key parts of your existing code base already do. Personally I
>> have
>>> reinvented:
>>>
>>> * Equal
>>> * Validation (badly I might add)
>>> * Iteratees
>>> * Ephemeral stream
>>> * Tree based zippers (although my implementation better fits my needs)
>>>
>>> I was for a time also on the verge of reinventing arrows.
>>>
> Of course these are useful concepts in scalaz! But the approach that you
> have to understand it in its entirety is wrong, IMO. And I believe few of
> the scalaz maintainers would claim that you need to. Also, sometimes it's
> more enlightening if you _do_ rediscover some of these features yourself
> than if you are made to swallow the whole tower of abstraction at one go.
> Makes you more appreciate their usefulness.
>
> A criticism of category theory, which I share, is not that it does not
> present useful concepts. In a sense category theory is the most general of
> all theories so of course it will describe a lot of useful concepts. The
> criticism is that the concepts covered by category theory tend to be very
> general but are often not very deep*, and the overhead of learning category
> theory is not paid back by the usefulness of applying it. That's why
> category theory did not make greater inroads into mathematics and computer
> science (it was quite fashionable in both branches for a while, at
> different periods in time).
>
> * By deep, I mean: the _application_ of the concept in a concrete scenario
> would otherwise require a hard proof (if we talk about mathematics) or very
> involved code (if we talk about computing).
>
> My favorite here is the Richard Feynman auto-biography, where he talks
> about Brasilian physics education of the 60s. That education was very
> abstract and deductive. It presented a bunch of laws which students had to
> memorize, but could not apply to anything real. Feynman was very critical
> of this approach, of course.
>
> So, I believe if scalaz should have wider appeal to people, it will need to
> stress self-discovery more. Instead of just pushing a library out, develop
> material how people can discover central abstractions themselves. Another
> great example how that's done is Structure and Interpretation of Computer
> Programming by Abelson and Sussman.
>
> Cheers
>

On Sun, Nov 20, 2011 at 11:59 AM, Tony Morris <tonymorris@gmail.com> wrote:

On 20/11/11 20:52, martin odersky wrote:
> On Sun, Nov 20, 2011 at 11:03 AM, Tony Morris <tonymorris@gmail.com> wrote:
>
>> On 20/11/11 19:58, Chris Twiner wrote:
>>> I want to "quickly" comment on the whole Scalaz documentation/complexity
>>> thing.
>>>
>>> Disclaimer: I say this as an (ab)user of Scalaz.
>>>
>>> Programming is hard, learning totally new concepts is hard - the payoff
>> has
>>> to be worth the investment.  Documentation should provide enough of an
>>> overview to answer the "is it worth it" question.
>>>
>>> Here Scalaz documentation is poor. It takes way too much time to be able
>> to
>>> understand the why's and, perhaps more importantly the how's. The why's I
>>> will come back to, but the how's will be solved in large part by Scalaz
>> 7.
>>> 7 makes a big shift in code organization, putting most type class
>> instances
>>> right with their related type (not spread out over a few files). Scaladoc
>>> should then be a usable tool for discovering the how.
>>>
>>> The why's on the other hand require a bit of searching - see the deriving
>>> presentations and read those scary Runar blog posts, hell you can even
>> read
>>> about Elephants if it helps. I believe that the upcoming book might
>> provide
>>> the overview that most need.
>>>
>>> The important part is this: you will reinvent parts of Scalaz sooner or
>>> later. Key parts of your existing code base already do.  Personally I
>> have
>>> reinvented:
>>>
>>> * Equal
>>> * Validation (badly I might add)
>>> * Iteratees
>>> * Ephemeral stream
>>> * Tree based zippers (although my implementation better fits my needs)
>>>
>>> I was for a time also on the verge of reinventing arrows.
>>>
> Of course these are useful concepts in scalaz! But the approach that you
> have to understand it in its entirety is wrong, IMO. And I believe few of
> the scalaz maintainers would claim that you need to. Also, sometimes it's
> more enlightening if you _do_ rediscover some of these features yourself
> than if you are made to swallow the whole tower of abstraction at one go.
> Makes you more appreciate their usefulness.
>
> A criticism of category theory, which I share, is not that it does not
> present useful concepts. In a sense category theory is the most general of
> all theories so of course it will describe a lot of useful concepts. The
> criticism is that the concepts covered by category theory tend to be very
> general but are often not very deep*, and the overhead of learning category
> theory is not paid back by the usefulness of applying it. That's why
> category theory did not make greater inroads into mathematics and computer
> science (it was quite fashionable in both branches for a while, at
> different periods in time).
>
> * By deep, I mean: the _application_ of the concept in a concrete scenario
> would otherwise require a hard proof (if we talk about mathematics) or very
> involved code (if we talk about computing).
>
> My favorite here is the Richard Feynman auto-biography, where he talks
> about Brasilian physics education of the 60s. That education was very
> abstract and deductive. It presented a bunch of laws which students had to
> memorize, but could not apply to anything real. Feynman was very critical
> of this approach, of course.
>
> So, I believe if scalaz should have wider appeal to people, it will need to
> stress self-discovery more. Instead of just pushing a library out, develop
> material how people can discover central abstractions themselves. Another
> great example how that's done is Structure and Interpretation of Computer
> Programming by Abelson and Sussman.
>
> Cheers
>
>  -- Martin
>

Martin,
How do you propose we get people to knowingly discover concepts (in
contrast to unknowingly discover, as they currently do), when you have
seen the general attitude to learning these things? It's much tougher
than you might imagine -- indeed, look at the roundabout we went on
before you discovered that you'd invented "the essence of the iterator
pattern" in a previous thread. What about others?

You regularly ask me why I bother with this mailing list -- now I can
answer. It's because occasionally someone will contact me, in private or
something, who has had a genuine insight and is looking for discovery.
It's cheap for me when that happens because all I need to do is give the
appropriate leads and that person(s) goes off to discover for
themselves. Like I said, time management is not difficult and I will
pick off the easy fruit on this mailing list -- this includes putting up
strong resistance to the anti-think squad, which is important to others'
learning.

The fact that you describe them as the anti-think squad is insulting. They choose not to specialize in your area. They have other problems to worry about. Just let them do that instead of calling them names.
 -- Martin

On 20/11/11 21:07, martin odersky wrote:
> On Sun, Nov 20, 2011 at 11:59 AM, Tony Morris wrote:
>
>> On 20/11/11 20:52, martin odersky wrote:
>>> On Sun, Nov 20, 2011 at 11:03 AM, Tony Morris
>> wrote:
>>>> On 20/11/11 19:58, Chris Twiner wrote:
>>>>> I want to "quickly" comment on the whole Scalaz
>> documentation/complexity
>>>>> thing.
>>>>>
>>>>> Disclaimer: I say this as an (ab)user of Scalaz.
>>>>>
>>>>> Programming is hard, learning totally new concepts is hard - the payoff
>>>> has
>>>>> to be worth the investment. Documentation should provide enough of an
>>>>> overview to answer the "is it worth it" question.
>>>>>
>>>>> Here Scalaz documentation is poor. It takes way too much time to be
>> able
>>>> to
>>>>> understand the why's and, perhaps more importantly the how's. The
>> why's I
>>>>> will come back to, but the how's will be solved in large part by Scalaz
>>>> 7.
>>>>> 7 makes a big shift in code organization, putting most type class
>>>> instances
>>>>> right with their related type (not spread out over a few files).
>> Scaladoc
>>>>> should then be a usable tool for discovering the how.
>>>>>
>>>>> The why's on the other hand require a bit of searching - see the
>> deriving
>>>>> presentations and read those scary Runar blog posts, hell you can even
>>>> read
>>>>> about Elephants if it helps. I believe that the upcoming book might
>>>> provide
>>>>> the overview that most need.
>>>>>
>>>>> The important part is this: you will reinvent parts of Scalaz sooner or
>>>>> later. Key parts of your existing code base already do. Personally I
>>>> have
>>>>> reinvented:
>>>>>
>>>>> * Equal
>>>>> * Validation (badly I might add)
>>>>> * Iteratees
>>>>> * Ephemeral stream
>>>>> * Tree based zippers (although my implementation better fits my needs)
>>>>>
>>>>> I was for a time also on the verge of reinventing arrows.
>>>>>
>>> Of course these are useful concepts in scalaz! But the approach that you
>>> have to understand it in its entirety is wrong, IMO. And I believe few of
>>> the scalaz maintainers would claim that you need to. Also, sometimes it's
>>> more enlightening if you _do_ rediscover some of these features yourself
>>> than if you are made to swallow the whole tower of abstraction at one go.
>>> Makes you more appreciate their usefulness.
>>>
>>> A criticism of category theory, which I share, is not that it does not
>>> present useful concepts. In a sense category theory is the most general
>> of
>>> all theories so of course it will describe a lot of useful concepts. The
>>> criticism is that the concepts covered by category theory tend to be very
>>> general but are often not very deep*, and the overhead of learning
>> category
>>> theory is not paid back by the usefulness of applying it. That's why
>>> category theory did not make greater inroads into mathematics and
>> computer
>>> science (it was quite fashionable in both branches for a while, at
>>> different periods in time).
>>>
>>> * By deep, I mean: the _application_ of the concept in a concrete
>> scenario
>>> would otherwise require a hard proof (if we talk about mathematics) or
>> very
>>> involved code (if we talk about computing).
>>>
>>> My favorite here is the Richard Feynman auto-biography, where he talks
>>> about Brasilian physics education of the 60s. That education was very
>>> abstract and deductive. It presented a bunch of laws which students had
>> to
>>> memorize, but could not apply to anything real. Feynman was very critical
>>> of this approach, of course.
>>>
>>> So, I believe if scalaz should have wider appeal to people, it will need
>> to
>>> stress self-discovery more. Instead of just pushing a library out,
>> develop
>>> material how people can discover central abstractions themselves. Another
>>> great example how that's done is Structure and Interpretation of Computer
>>> Programming by Abelson and Sussman.
>>>
>>> Cheers
>>>
>>> -- Martin
>>>
>> Martin,
>> How do you propose we get people to knowingly discover concepts (in
>> contrast to unknowingly discover, as they currently do), when you have
>> seen the general attitude to learning these things? It's much tougher
>> than you might imagine -- indeed, look at the roundabout we went on
>> before you discovered that you'd invented "the essence of the iterator
>> pattern" in a previous thread. What about others?
>>
>> You regularly ask me why I bother with this mailing list -- now I can
>> answer. It's because occasionally someone will contact me, in private or
>> something, who has had a genuine insight and is looking for discovery.
>> It's cheap for me when that happens because all I need to do is give the
>> appropriate leads and that person(s) goes off to discover for
>> themselves. Like I said, time management is not difficult and I will
>> pick off the easy fruit on this mailing list -- this includes putting up
>> strong resistance to the anti-think squad, which is important to others'
>> learning.
>>
> The fact that you describe them as the anti-think squad is insulting. They
> choose not to specialize in your area. They have other problems to worry
> about. Just let them do that instead of calling them names.
>

My point is exactly that the documentation is *not* in the types.

Let's get things straight.  Scalaz is a useful library.   I don't mean to bash it's utility.

I do mean to bash the notion that the types *on their own* convey meaning.   That meaning exists by nature of a description of the abstract concept.

Yes there are papers and such for these concepts, but there is little linkage between scalaz and these concepts in the lib itself.  You can claim "this is because we want to remain useful", but I think this is a bogus reason.

Scalaz has enough types that have 'funny' names that required a browse the source code to figure out which concept was really being used.  Some days I don't have time for that when looking for a utility.

ValidationNel?  If I see its definition it makes perfect sense, if I know how Validation works in scala (you see a Validation is not something which can validate another, but something that can *be* validated since it is in one or more states.)

Yes the 'documentation is in the type' but you're using nonsense vocabulary if you don't provide a dictionary of types and definitions.   In Scala, such a dictionary is scaladoc.  We're not used to looking externally for hoe something works.   Like I said, this is my biggest frustration with scalaz and *used to be* a big frustration with scala itself.   Luckily a few docspree (*not organized by typesafe*) helped fix it.

I'd suggest organizing a Scalaz docspree.  They're pretty fun and can help teach others the concept.  For a library where the founders are so great at teaching, it's shocking to me that an easy to use type-to-definition dictionary does not exist.

Note: I'm willing to help document scalaz (in scaladoc).  Like I said, the library is useful, but learning from it is frustrating. 

On Nov 19, 2011 9:47 PM, "Richard Wallace" <rwallace@thewallacepack.net> wrote:

On Sat, Nov 19, 2011 at 11:33 AM, Josh Suereth <joshua.suereth@gmail.com> wrote:
> People ascribe names to abstract things all the time.   When I say "fire", I
> may be referring to all my experiences of fire as an abstract concept.  Your
> mind interrupts it and ascribes the aspects of fire that it knows to the
> words I am using.
> The same is true with names.  To Say that the more abstract a thing, the
> less important the name is BOGUS, bunk.   WHY oh why to we ascribe silly
> names to abstract concepts like:
> Monad
> Monoid
> Eigenvector
> Nullspace
> monomorphism
> Jacobian
> My opinion is that the more abstract a concept, usually the longer or
> sillier the name (probably because they're named after the person who first
> *described* the abstract concept).
> You see, if I give something a name and a description, I can start using the
> name in place of the description.   This is what language is all about.
> Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor to
> me at all.  Again, I can come up with a class Graph where these names make a
> *lot* of sense.
> Even in the case of "def equals(that: Any): Boolean", we still use "that" or
> "rhs" instead of "x" or "y", Where "that" refers to "something that is not
> htis" and "rhs" refers to the right-hand-side of an expression.   These
> words connote *meaning* and only as much meaning as needed to determine what
> the variable is doing.
>
> trait TypeFunctor {
>   type F[x]
>   def map[X, Y](f: X => Y): F[X] => F[Y]
> }
> To those who don't understand the concepts of functors, these names are
> pretty poor.  However, if I *document* the concepts I'm using.
> /** A type functor is a mapping between two categories of types.   A functor
> can take any type in the first category and
>  * map it onto a second category (of still types).
>  */
> trait TypeFunctor {
>   /** This type constructor is used to map any type from the initial
> category (of all possible types) into another category
>    * (that may or may not consist of all types).
>    * @tparam X  The type to be mapped into the new category
>    * @return  The type in the second category.
>    */
>   type F[X]
>   /**
>    *  This method takes  a type morphism (an arrow between points A and B in
> the initial category.
>    *  Note: A morphism in types is a function that can convert elements of
> type A into type B).
>    *  The type morphism is mapped it into the new category defined by the
> functor.
>    *  defined by this functor.
>    *
>    *  @tparam A  The initial type of the input morphism.
>    *  @tparam B  The final type of the input morphism
>    *  @param f  The morphism (function) that can map elements of type A into
> type B
>    *  @returns  A morphism that can take values in the mapped category of
> this functor.
>    */
>   def map[A, B](f: A => B): F[A] => F[B]
> }
> NOW, I've given *descriptions* to my abstract types.   Now when people see
> "A" and "B" in the context of the class, there's a bit of meaning attached
> to the names, which are accurate.   When I use "F[?]" in later code, I've
> defined what F is in my source code, so users can understand it.
> Scalaz is the *most* disappointing library in the scala ecosystem due to
> it's lack of documentation and poor naming choice.

That's not really fair, is it?  I would say that the most
disappointing library has to be the Scala standard library.  When I
started using Scala I couldn't make heads or tails of anything.  I had
to read books and blogs to understand what was useful to accomplish
the tasks at hand.  There were and still are several places in the
scaladoc where concepts - some only known in the Scala community - are
used in a brief sentence describing a method, but no further
explanation is given.  This is pretty piss poor for something at the
very core of the language.

Now I'm sure you and everybody else are getting ready to hit the reply
button to tell me all about the great strides that have been made in
documenting the standard lib.  And I agree, it has gotten much better
lately.  But that didn't happen until Typesafe was founded and the
focus of the Scala creators and maintainers shifted from making Scala
useful to getting Scala used.

Scalaz's creators and maintainers are currently more focused on making
something useful rather than something that is widely used.  There is
a ton of documentation in Scalaz - it's all in the types! - and there
is voluminous amounts of pdfs and blogs about the underlying concepts.
 No, that documentation has not been *copied* into the source code.
That has not been a focus.  It is expected that people interested
enough in learning will Google the concept or ask on the mailing list.
 But if you, or anyone else, wants to improve the situation submit a
pull request.  As long as descriptions are accurate, they'll be
accepted.

Rich

> If you wish others to
> understand an abstract concept, you need to provide a description for that
> concept.   Until you do so, it's just meaningless gibberish.  Scalaz *still*
> suffers from this, despite good efforts from some.  Claiming that abstract
> concepts are "lessened' through good names and documentation is bunk, bogus
> and disappointing to find.
> One *could* argue that the source code is the description used for the name.
>  I could use this excuse to have horrible names throughout my codebase, even
> if a well known name was available and would help ease someone's ability to
> learn the concepts in my library.   I don't buy it.
> So, as in all things, *naming* is difficult.   A poor name can convey the
> *wrong* meaning.   However, conveying *no* meaning is perhaps just as poor.
>   If you're going to use an abstract name (like X or A) for something,
> please document a description if possible.    If the variable has no meaning
> to be conveyed, then why is it in your source code?
> Even non-english words like "Oooga Booga" convey some meaning.
> - Josh
>
>
> On Sat, Nov 19, 2011 at 4:46 AM, Philippe Lhoste <PhiLho@gmx.net> wrote:
>>
>> On 18/11/2011 01:57, Kenneth McDonald wrote:
>>>
>>> Sorry Tony, but from a software engineering/maintainability point of
>>> view the statement that "type variable names contain no context" is just
>>> as crazy as (and no crazier than) the statement that "program variable
>>> names contain no context". Code is intended to be used in a context, not
>>> matter how general (but as a general point, usually not too general).
>>> Names identify and anchor that context. This is _incredibly_ important
>>> to reusable software.
>>
>> I have to disagree, at least partially, here. Some software is highly
>> reusable just because they don't have a context...
>> I barely know Scalaz, mostly from what I have read here and there, but my
>> understanding is that it is very abstract, disconnected from specific
>> domains ("business logic"). Yet people find it very useful, because they
>> mastered the mechanisms it offers, and find them very useful when applied to
>> *their* business logic.
>> Somehow, it seems like a kind of meta-programming, offering tools to be
>> used in a more specific domain.
>>
>> I see this kind of tool as highly reusable, yet without identity.
>> Somehow, it is similar for the collection library.
>>
>> Of course, you can still name (semi-)abstract stuff, like "the thing we
>> iterate on", "the type of the cumulated result" or such.
>> Of course, in some domains, the names can draw on the underlying theory:
>> nodes and edges in graph theory, key and values in data maps, and so on. But
>> overall, specific names can get in the way.
>>
>> Perhaps what is missing from the Scala doc is context. Somehow, it lists
>> together several methods but description is short, context can be missing,
>> etc.
>>
>> I don't think the tradition of one letter type names will go away, but in
>> a few entries of ScalaDoc I looked at, the types are (succinctly) explained
>> in the Scala doc itself. So even if the names aren't very explicit, the doc
>> is here.
>>
>> --
>> Philippe Lhoste
>> --  (near) Paris -- France
>> --  http://Phi.Lho.free.fr
>> --  --  --  --  --  --  --  --  --  --  --  --  --  --
>>
>
>

Tony -

Scalaz didn't block just anyone from learning concepts,  it blocked me (someone who really wanted to learn these concepts)  until enough blogs and things are available.  I wound up learning haskell snce scalaz docs were so poor.  As chris said, you end up reinventing portions of scalaz at times.  I wouldn't do this if I had been able to understand what a type like ValidationNel was for before the blog posts were written.

Category theory can be a useful way to compose behavior of functions.   It's like design patterns for FP but can be exposed directly. These are abstract concepts and hard to learn.  Scalaz does itself a disservice by providing poor documentation for those like me (not coming from Haskell.)

I think you'll always have folks who find category theory too abstract, but the point is better documentation can help a lot of us learn.

Back to the original point:   a name used in code is only as good as its definition.   Sometimes using a longer name for a type parameter means I can convey a better definition.   Sometimes it could be worse. 

On Nov 20, 2011 5:59 AM, "Tony Morris" <tonymorris@gmail.com> wrote:

On 20/11/11 20:52, martin odersky wrote:
> On Sun, Nov 20, 2011 at 11:03 AM, Tony Morris <tonymorris@gmail.com> wrote:
>
>> On 20/11/11 19:58, Chris Twiner wrote:
>>> I want to "quickly" comment on the whole Scalaz documentation/complexity
>>> thing.
>>>
>>> Disclaimer: I say this as an (ab)user of Scalaz.
>>>
>>> Programming is hard, learning totally new concepts is hard - the payoff
>> has
>>> to be worth the investment.  Documentation should provide enough of an
>>> overview to answer the "is it worth it" question.
>>>
>>> Here Scalaz documentation is poor. It takes way too much time to be able
>> to
>>> understand the why's and, perhaps more importantly the how's. The why's I
>>> will come back to, but the how's will be solved in large part by Scalaz
>> 7.
>>> 7 makes a big shift in code organization, putting most type class
>> instances
>>> right with their related type (not spread out over a few files). Scaladoc
>>> should then be a usable tool for discovering the how.
>>>
>>> The why's on the other hand require a bit of searching - see the deriving
>>> presentations and read those scary Runar blog posts, hell you can even
>> read
>>> about Elephants if it helps. I believe that the upcoming book might
>> provide
>>> the overview that most need.
>>>
>>> The important part is this: you will reinvent parts of Scalaz sooner or
>>> later. Key parts of your existing code base already do.  Personally I
>> have
>>> reinvented:
>>>
>>> * Equal
>>> * Validation (badly I might add)
>>> * Iteratees
>>> * Ephemeral stream
>>> * Tree based zippers (although my implementation better fits my needs)
>>>
>>> I was for a time also on the verge of reinventing arrows.
>>>
> Of course these are useful concepts in scalaz! But the approach that you
> have to understand it in its entirety is wrong, IMO. And I believe few of
> the scalaz maintainers would claim that you need to. Also, sometimes it's
> more enlightening if you _do_ rediscover some of these features yourself
> than if you are made to swallow the whole tower of abstraction at one go.
> Makes you more appreciate their usefulness.
>
> A criticism of category theory, which I share, is not that it does not
> present useful concepts. In a sense category theory is the most general of
> all theories so of course it will describe a lot of useful concepts. The
> criticism is that the concepts covered by category theory tend to be very
> general but are often not very deep*, and the overhead of learning category
> theory is not paid back by the usefulness of applying it. That's why
> category theory did not make greater inroads into mathematics and computer
> science (it was quite fashionable in both branches for a while, at
> different periods in time).
>
> * By deep, I mean: the _application_ of the concept in a concrete scenario
> would otherwise require a hard proof (if we talk about mathematics) or very
> involved code (if we talk about computing).
>
> My favorite here is the Richard Feynman auto-biography, where he talks
> about Brasilian physics education of the 60s. That education was very
> abstract and deductive. It presented a bunch of laws which students had to
> memorize, but could not apply to anything real. Feynman was very critical
> of this approach, of course.
>
> So, I believe if scalaz should have wider appeal to people, it will need to
> stress self-discovery more. Instead of just pushing a library out, develop
> material how people can discover central abstractions themselves. Another
> great example how that's done is Structure and Interpretation of Computer
> Programming by Abelson and Sussman.
>
> Cheers
>
>  -- Martin
>

Martin,
How do you propose we get people to knowingly discover concepts (in
contrast to unknowingly discover, as they currently do), when you have
seen the general attitude to learning these things? It's much tougher
than you might imagine -- indeed, look at the roundabout we went on
before you discovered that you'd invented "the essence of the iterator
pattern" in a previous thread. What about others?

You regularly ask me why I bother with this mailing list -- now I can
answer. It's because occasionally someone will contact me, in private or
something, who has had a genuine insight and is looking for discovery.
It's cheap for me when that happens because all I need to do is give the
appropriate leads and that person(s) goes off to discover for
themselves. Like I said, time management is not difficult and I will
pick off the easy fruit on this mailing list -- this includes putting up
strong resistance to the anti-think squad, which is important to others'
learning.

PS: You really need to let go of the category theory thing. It is
absolutely not representative of what we are discussing.


--
Tony Morris
http://tmorris.net/

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am 20.11.2011 13:08, schrieb Josh Suereth:

> Scalaz has enough types that have 'funny' names that required a
> browse the source code to figure out which concept was really being
> used. Some days I don't have time for that when looking for a
> utility.
> ...
> Luckily a few docspree (*not organized by typesafe*)

Apropos meaning - what is the meaning of "Docspree" - where does the
name origin? I'm living close to river Spree, but I fear it doesn't help
me much in understanding. dict.leo.org was of no help too.

On Sun, Nov 20, 2011 at 8:20 AM, Stefan Wagner wrote:
> Apropos meaning - what is the meaning of "Docspree" - where does the
> name origin? I'm living close to river Spree, but I fear it doesn't help
> me much in understanding. dict.leo.org was of no help too.

The word "spree" is usually preceded by either "killing" or
"spending", two subjects we Americans know a lot about.

"An unrestrained indulgence in or outburst of an activity", says the dictionary.

On Sun, Nov 20, 2011 at 5:08 AM, Josh Suereth wrote:
> My point is exactly that the documentation is *not* in the types.
>

But it is. You're own example shows that. What is so cryptic about
fmap[A, B](fa: F[A])(f: A => B): F[B]? Your description would
probably scare beginners because it introduces many new concepts. A
simpler description would be "Maps (transforms/converts) A(s) inside F
to B(s)." And that's exactly what the types say!

> Let's get things straight.  Scalaz is a useful library.   I don't mean to
> bash it's utility.
>
> I do mean to bash the notion that the types *on their own* convey meaning.
> That meaning exists by nature of a description of the abstract concept.
>
> Yes there are papers and such for these concepts, but there is little
> linkage between scalaz and these concepts in the lib itself.  You can claim
> "this is because we want to remain useful", but I think this is a bogus
> reason.
>

I didn't say, "we want to remain useful." I said the focus is on being
useful, not on being widely used. This means that we spend our time
adding new abstractions and utility. I'd really like to see some of
the concepts described in scaladoc too. But that hasn't been
something anyone has prioritized because there *are* voluminous
amounts of documentation already out there and improving it's
usefulness seems far more important at this point.

> Scalaz has enough types that have 'funny' names that required a browse the
> source code to figure out which concept was really being used.  Some days I
> don't have time for that when looking for a utility.
>
> ValidationNel?  If I see its definition it makes perfect sense, if I know
> how Validation works in scala (you see a Validation is not something which
> can validate another, but something that can *be* validated since it is in
> one or more states.)
>
> Yes the 'documentation is in the type' but you're using nonsense vocabulary
> if you don't provide a dictionary of types and definitions.   In Scala, such
> a dictionary is scaladoc.  We're not used to looking externally for hoe
> something works.   Like I said, this is my biggest frustration with scalaz
> and *used to be* a big frustration with scala itself.   Luckily a few
> docspree (*not organized by typesafe*) helped fix it.
>
> I'd suggest organizing a Scalaz docspree.  They're pretty fun and can help
> teach others the concept.  For a library where the founders are so great at
> teaching, it's shocking to me that an easy to use type-to-definition
> dictionary does not exist.
>

Rather than suggesting, why not do it yourself?

> Note: I'm willing to help document scalaz (in scaladoc).  Like I said, the
> library is useful, but learning from it is frustrating.
>
> On Nov 19, 2011 9:47 PM, "Richard Wallace"
> wrote:
>>
>> On Sat, Nov 19, 2011 at 11:33 AM, Josh Suereth
>> wrote:
>> > People ascribe names to abstract things all the time.   When I say
>> > "fire", I
>> > may be referring to all my experiences of fire as an abstract concept.
>> >  Your
>> > mind interrupts it and ascribes the aspects of fire that it knows to the
>> > words I am using.
>> > The same is true with names.  To Say that the more abstract a thing, the
>> > less important the name is BOGUS, bunk.   WHY oh why to we ascribe silly
>> > names to abstract concepts like:
>> > Monad
>> > Monoid
>> > Eigenvector
>> > Nullspace
>> > monomorphism
>> > Jacobian
>> > My opinion is that the more abstract a concept, usually the longer or
>> > sillier the name (probably because they're named after the person who
>> > first
>> > *described* the abstract concept).
>> > You see, if I give something a name and a description, I can start using
>> > the
>> > name in place of the description.   This is what language is all about.
>> > Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor
>> > to
>> > me at all.  Again, I can come up with a class Graph where these names
>> > make a
>> > *lot* of sense.
>> > Even in the case of "def equals(that: Any): Boolean", we still use
>> > "that" or
>> > "rhs" instead of "x" or "y", Where "that" refers to "something that is
>> > not
>> > htis" and "rhs" refers to the right-hand-side of an expression.   These
>> > words connote *meaning* and only as much meaning as needed to determine
>> > what
>> > the variable is doing.
>> >
>> > trait TypeFunctor {
>> >   type F[x]
>> >   def map[X, Y](f: X => Y): F[X] => F[Y]
>> > }
>> > To those who don't understand the concepts of functors, these names are
>> > pretty poor.  However, if I *document* the concepts I'm using.
>> > /** A type functor is a mapping between two categories of types.   A
>> > functor
>> > can take any type in the first category and
>> >  * map it onto a second category (of still types).
>> >  */
>> > trait TypeFunctor {
>> >   /** This type constructor is used to map any type from the initial
>> > category (of all possible types) into another category
>> >    * (that may or may not consist of all types).
>> >    * @tparam X  The type to be mapped into the new category
>> >    * @return  The type in the second category.
>> >    */
>> >   type F[X]
>> >   /**
>> >    *  This method takes  a type morphism (an arrow between points A and
>> > B in
>> > the initial category.
>> >    *  Note: A morphism in types is a function that can convert elements
>> > of
>> > type A into type B).
>> >    *  The type morphism is mapped it into the new category defined by
>> > the
>> > functor.
>> >    *  defined by this functor.
>> >    *
>> >    *  @tparam A  The initial type of the input morphism.
>> >    *  @tparam B  The final type of the input morphism
>> >    *  @param f  The morphism (function) that can map elements of type A
>> > into
>> > type B
>> >    *  @returns  A morphism that can take values in the mapped category
>> > of
>> > this functor.
>> >    */
>> >   def map[A, B](f: A => B): F[A] => F[B]
>> > }
>> > NOW, I've given *descriptions* to my abstract types.   Now when people
>> > see
>> > "A" and "B" in the context of the class, there's a bit of meaning
>> > attached
>> > to the names, which are accurate.   When I use "F[?]" in later code,
>> > I've
>> > defined what F is in my source code, so users can understand it.
>> > Scalaz is the *most* disappointing library in the scala ecosystem due to
>> > it's lack of documentation and poor naming choice.
>>
>> That's not really fair, is it?  I would say that the most
>> disappointing library has to be the Scala standard library.  When I
>> started using Scala I couldn't make heads or tails of anything.  I had
>> to read books and blogs to understand what was useful to accomplish
>> the tasks at hand.  There were and still are several places in the
>> scaladoc where concepts - some only known in the Scala community - are
>> used in a brief sentence describing a method, but no further
>> explanation is given.  This is pretty piss poor for something at the
>> very core of the language.
>>
>> Now I'm sure you and everybody else are getting ready to hit the reply
>> button to tell me all about the great strides that have been made in
>> documenting the standard lib.  And I agree, it has gotten much better
>> lately.  But that didn't happen until Typesafe was founded and the
>> focus of the Scala creators and maintainers shifted from making Scala
>> useful to getting Scala used.
>>
>> Scalaz's creators and maintainers are currently more focused on making
>> something useful rather than something that is widely used.  There is
>> a ton of documentation in Scalaz - it's all in the types! - and there
>> is voluminous amounts of pdfs and blogs about the underlying concepts.
>>  No, that documentation has not been *copied* into the source code.
>> That has not been a focus.  It is expected that people interested
>> enough in learning will Google the concept or ask on the mailing list.
>>  But if you, or anyone else, wants to improve the situation submit a
>> pull request.  As long as descriptions are accurate, they'll be
>> accepted.
>>
>> Rich
>>
>> > If you wish others to
>> > understand an abstract concept, you need to provide a description for
>> > that
>> > concept.   Until you do so, it's just meaningless gibberish.  Scalaz
>> > *still*
>> > suffers from this, despite good efforts from some.  Claiming that
>> > abstract
>> > concepts are "lessened' through good names and documentation is bunk,
>> > bogus
>> > and disappointing to find.
>> > One *could* argue that the source code is the description used for the
>> > name.
>> >  I could use this excuse to have horrible names throughout my codebase,
>> > even
>> > if a well known name was available and would help ease someone's ability
>> > to
>> > learn the concepts in my library.   I don't buy it.
>> > So, as in all things, *naming* is difficult.   A poor name can convey
>> > the
>> > *wrong* meaning.   However, conveying *no* meaning is perhaps just as
>> > poor.
>> >   If you're going to use an abstract name (like X or A) for something,
>> > please document a description if possible.    If the variable has no
>> > meaning
>> > to be conveyed, then why is it in your source code?
>> > Even non-english words like "Oooga Booga" convey some meaning.
>> > - Josh
>> >
>> >
>> > On Sat, Nov 19, 2011 at 4:46 AM, Philippe Lhoste wrote:
>> >>
>> >> On 18/11/2011 01:57, Kenneth McDonald wrote:
>> >>>
>> >>> Sorry Tony, but from a software engineering/maintainability point of
>> >>> view the statement that "type variable names contain no context" is
>> >>> just
>> >>> as crazy as (and no crazier than) the statement that "program variable
>> >>> names contain no context". Code is intended to be used in a context,
>> >>> not
>> >>> matter how general (but as a general point, usually not too general).
>> >>> Names identify and anchor that context. This is _incredibly_ important
>> >>> to reusable software.
>> >>
>> >> I have to disagree, at least partially, here. Some software is highly
>> >> reusable just because they don't have a context...
>> >> I barely know Scalaz, mostly from what I have read here and there, but
>> >> my
>> >> understanding is that it is very abstract, disconnected from specific
>> >> domains ("business logic"). Yet people find it very useful, because
>> >> they
>> >> mastered the mechanisms it offers, and find them very useful when
>> >> applied to
>> >> *their* business logic.
>> >> Somehow, it seems like a kind of meta-programming, offering tools to be
>> >> used in a more specific domain.
>> >>
>> >> I see this kind of tool as highly reusable, yet without identity.
>> >> Somehow, it is similar for the collection library.
>> >>
>> >> Of course, you can still name (semi-)abstract stuff, like "the thing we
>> >> iterate on", "the type of the cumulated result" or such.
>> >> Of course, in some domains, the names can draw on the underlying
>> >> theory:
>> >> nodes and edges in graph theory, key and values in data maps, and so
>> >> on. But
>> >> overall, specific names can get in the way.
>> >>
>> >> Perhaps what is missing from the Scala doc is context. Somehow, it
>> >> lists
>> >> together several methods but description is short, context can be
>> >> missing,
>> >> etc.
>> >>
>> >> I don't think the tradition of one letter type names will go away, but
>> >> in
>> >> a few entries of ScalaDoc I looked at, the types are (succinctly)
>> >> explained
>> >> in the Scala doc itself. So even if the names aren't very explicit, the
>> >> doc
>> >> is here.
>> >>
>> >> --
>> >> Philippe Lhoste
>> >> --  (near) Paris -- France
>> >> --  http://Phi.Lho.free.fr
>> >> --  --  --  --  --  --  --  --  --  --  --  --  --  --
>> >>
>> >
>> >
>

I already help with scala's docsprees and I had a local fork of scalaz 6 with my own scaladoc I was going to contribute, but for scalaz 7 changing it's underlying architecture (for the better, really).

Here's another example, Iteratees.   The type signature is Iteratee[I, M, O], not Iteratee[A, B, C].   This is to *hint* that an iteratee has an input type an output type and a monadic context.  

I can only infer this *if* I know what an iteratee is *and* I happened to read the paper that uses three type parameters to know there's a monad in there and there's some form of input consumption and output generation.   If I see Iteratee [String,IO,String]  I only know this to be a reader and producer of strings if I remember the Iteratee type and it's parameter ordering.  The type is not enough on its own without that additional, taken for granted implicit definition for iteratees I have.

Types only convey meaning if they have description/definitions somewhere.  This could even be an implicit definition.

So, I,M,O are infinitely better names than A,B,C.  I can denote more meaning through documentation or through different names.  Scalaz is an easy library to poke at here because it has a lot of abstract concepts that require lots or documentation (scaladocs most likely linking to external papers an Wikipedia articles) for the types to have definitions in folks heads.

The same issue existed, e.g. in SBT.  You need to know to read the user's guide wiki to learn how things work.   Its documentation does not target scaladoc users.   That's less frustrating from a build tool, but still frustrating.  Scalaz is a library.  It's custom behavior to use scaladocs to learn libraries in Scala.    Assuming otherwise is silly.

Expect documentation patches from me for the scalaz I use.

On Nov 20, 2011 9:55 AM, "Richard Wallace" <rwallace@thewallacepack.net> wrote:

On Sun, Nov 20, 2011 at 5:08 AM, Josh Suereth <joshua.suereth@gmail.com> wrote:
> My point is exactly that the documentation is *not* in the types.
>

But it is.  You're own example shows that.  What is so cryptic about
fmap[A, B](fa: F[A])(f: A => B): F[B]?  Your description would
probably scare beginners because it introduces many new concepts.  A
simpler description would be "Maps (transforms/converts) A(s) inside F
to B(s)."  And that's exactly what the types say!

> Let's get things straight.  Scalaz is a useful library.   I don't mean to
> bash it's utility.
>
> I do mean to bash the notion that the types *on their own* convey meaning.
> That meaning exists by nature of a description of the abstract concept.
>
> Yes there are papers and such for these concepts, but there is little
> linkage between scalaz and these concepts in the lib itself.  You can claim
> "this is because we want to remain useful", but I think this is a bogus
> reason.
>

I didn't say, "we want to remain useful." I said the focus is on being
useful, not on being widely used.  This means that we spend our time
adding new abstractions and utility.  I'd really like to see some of
the concepts described in scaladoc too.  But that hasn't been
something anyone has prioritized because there *are* voluminous
amounts of documentation already out there and improving it's
usefulness seems far more important at this point.

> Scalaz has enough types that have 'funny' names that required a browse the
> source code to figure out which concept was really being used.  Some days I
> don't have time for that when looking for a utility.
>
> ValidationNel?  If I see its definition it makes perfect sense, if I know
> how Validation works in scala (you see a Validation is not something which
> can validate another, but something that can *be* validated since it is in
> one or more states.)
>
> Yes the 'documentation is in the type' but you're using nonsense vocabulary
> if you don't provide a dictionary of types and definitions.   In Scala, such
> a dictionary is scaladoc.  We're not used to looking externally for hoe
> something works.   Like I said, this is my biggest frustration with scalaz
> and *used to be* a big frustration with scala itself.   Luckily a few
> docspree (*not organized by typesafe*) helped fix it.
>
> I'd suggest organizing a Scalaz docspree.  They're pretty fun and can help
> teach others the concept.  For a library where the founders are so great at
> teaching, it's shocking to me that an easy to use type-to-definition
> dictionary does not exist.
>

Rather than suggesting, why not do it yourself?

> Note: I'm willing to help document scalaz (in scaladoc).  Like I said, the
> library is useful, but learning from it is frustrating.
>
> On Nov 19, 2011 9:47 PM, "Richard Wallace" <rwallace@thewallacepack.net>
> wrote:
>>
>> On Sat, Nov 19, 2011 at 11:33 AM, Josh Suereth <joshua.suereth@gmail.com>
>> wrote:
>> > People ascribe names to abstract things all the time.   When I say
>> > "fire", I
>> > may be referring to all my experiences of fire as an abstract concept.
>> >  Your
>> > mind interrupts it and ascribes the aspects of fire that it knows to the
>> > words I am using.
>> > The same is true with names.  To Say that the more abstract a thing, the
>> > less important the name is BOGUS, bunk.   WHY oh why to we ascribe silly
>> > names to abstract concepts like:
>> > Monad
>> > Monoid
>> > Eigenvector
>> > Nullspace
>> > monomorphism
>> > Jacobian
>> > My opinion is that the more abstract a concept, usually the longer or
>> > sillier the name (probably because they're named after the person who
>> > first
>> > *described* the abstract concept).
>> > You see, if I give something a name and a description, I can start using
>> > the
>> > name in place of the description.   This is what language is all about.
>> > Graph[N,V] may be poor, but Graph[NodeData,VertixData] doesn't seem poor
>> > to
>> > me at all.  Again, I can come up with a class Graph where these names
>> > make a
>> > *lot* of sense.
>> > Even in the case of "def equals(that: Any): Boolean", we still use
>> > "that" or
>> > "rhs" instead of "x" or "y", Where "that" refers to "something that is
>> > not
>> > htis" and "rhs" refers to the right-hand-side of an expression.   These
>> > words connote *meaning* and only as much meaning as needed to determine
>> > what
>> > the variable is doing.
>> >
>> > trait TypeFunctor {
>> >   type F[x]
>> >   def map[X, Y](f: X => Y): F[X] => F[Y]
>> > }
>> > To those who don't understand the concepts of functors, these names are
>> > pretty poor.  However, if I *document* the concepts I'm using.
>> > /** A type functor is a mapping between two categories of types.   A
>> > functor
>> > can take any type in the first category and
>> >  * map it onto a second category (of still types).
>> >  */
>> > trait TypeFunctor {
>> >   /** This type constructor is used to map any type from the initial
>> > category (of all possible types) into another category
>> >    * (that may or may not consist of all types).
>> >    * @tparam X  The type to be mapped into the new category
>> >    * @return  The type in the second category.
>> >    */
>> >   type F[X]
>> >   /**
>> >    *  This method takes  a type morphism (an arrow between points A and
>> > B in
>> > the initial category.
>> >    *  Note: A morphism in types is a function that can convert elements
>> > of
>> > type A into type B).
>> >    *  The type morphism is mapped it into the new category defined by
>> > the
>> > functor.
>> >    *  defined by this functor.
>> >    *
>> >    *  @tparam A  The initial type of the input morphism.
>> >    *  @tparam B  The final type of the input morphism
>> >    *  @param f  The morphism (function) that can map elements of type A
>> > into
>> > type B
>> >    *  @returns  A morphism that can take values in the mapped category
>> > of
>> > this functor.
>> >    */
>> >   def map[A, B](f: A => B): F[A] => F[B]
>> > }
>> > NOW, I've given *descriptions* to my abstract types.   Now when people
>> > see
>> > "A" and "B" in the context of the class, there's a bit of meaning
>> > attached
>> > to the names, which are accurate.   When I use "F[?]" in later code,
>> > I've
>> > defined what F is in my source code, so users can understand it.
>> > Scalaz is the *most* disappointing library in the scala ecosystem due to
>> > it's lack of documentation and poor naming choice.
>>
>> That's not really fair, is it?  I would say that the most
>> disappointing library has to be the Scala standard library.  When I
>> started using Scala I couldn't make heads or tails of anything.  I had
>> to read books and blogs to understand what was useful to accomplish
>> the tasks at hand.  There were and still are several places in the
>> scaladoc where concepts - some only known in the Scala community - are
>> used in a brief sentence describing a method, but no further
>> explanation is given.  This is pretty piss poor for something at the
>> very core of the language.
>>
>> Now I'm sure you and everybody else are getting ready to hit the reply
>> button to tell me all about the great strides that have been made in
>> documenting the standard lib.  And I agree, it has gotten much better
>> lately.  But that didn't happen until Typesafe was founded and the
>> focus of the Scala creators and maintainers shifted from making Scala
>> useful to getting Scala used.
>>
>> Scalaz's creators and maintainers are currently more focused on making
>> something useful rather than something that is widely used.  There is
>> a ton of documentation in Scalaz - it's all in the types! - and there
>> is voluminous amounts of pdfs and blogs about the underlying concepts.
>>  No, that documentation has not been *copied* into the source code.
>> That has not been a focus.  It is expected that people interested
>> enough in learning will Google the concept or ask on the mailing list.
>>  But if you, or anyone else, wants to improve the situation submit a
>> pull request.  As long as descriptions are accurate, they'll be
>> accepted.
>>
>> Rich
>>
>> > If you wish others to
>> > understand an abstract concept, you need to provide a description for
>> > that
>> > concept.   Until you do so, it's just meaningless gibberish.  Scalaz
>> > *still*
>> > suffers from this, despite good efforts from some.  Claiming that
>> > abstract
>> > concepts are "lessened' through good names and documentation is bunk,
>> > bogus
>> > and disappointing to find.
>> > One *could* argue that the source code is the description used for the
>> > name.
>> >  I could use this excuse to have horrible names throughout my codebase,
>> > even
>> > if a well known name was available and would help ease someone's ability
>> > to
>> > learn the concepts in my library.   I don't buy it.
>> > So, as in all things, *naming* is difficult.   A poor name can convey
>> > the
>> > *wrong* meaning.   However, conveying *no* meaning is perhaps just as
>> > poor.
>> >   If you're going to use an abstract name (like X or A) for something,
>> > please document a description if possible.    If the variable has no
>> > meaning
>> > to be conveyed, then why is it in your source code?
>> > Even non-english words like "Oooga Booga" convey some meaning.
>> > - Josh
>> >
>> >
>> > On Sat, Nov 19, 2011 at 4:46 AM, Philippe Lhoste <PhiLho@gmx.net> wrote:
>> >>
>> >> On 18/11/2011 01:57, Kenneth McDonald wrote:
>> >>>
>> >>> Sorry Tony, but from a software engineering/maintainability point of
>> >>> view the statement that "type variable names contain no context" is
>> >>> just
>> >>> as crazy as (and no crazier than) the statement that "program variable
>> >>> names contain no context". Code is intended to be used in a context,
>> >>> not
>> >>> matter how general (but as a general point, usually not too general).
>> >>> Names identify and anchor that context. This is _incredibly_ important
>> >>> to reusable software.
>> >>
>> >> I have to disagree, at least partially, here. Some software is highly
>> >> reusable just because they don't have a context...
>> >> I barely know Scalaz, mostly from what I have read here and there, but
>> >> my
>> >> understanding is that it is very abstract, disconnected from specific
>> >> domains ("business logic"). Yet people find it very useful, because
>> >> they
>> >> mastered the mechanisms it offers, and find them very useful when
>> >> applied to
>> >> *their* business logic.
>> >> Somehow, it seems like a kind of meta-programming, offering tools to be
>> >> used in a more specific domain.
>> >>
>> >> I see this kind of tool as highly reusable, yet without identity.
>> >> Somehow, it is similar for the collection library.
>> >>
>> >> Of course, you can still name (semi-)abstract stuff, like "the thing we
>> >> iterate on", "the type of the cumulated result" or such.
>> >> Of course, in some domains, the names can draw on the underlying
>> >> theory:
>> >> nodes and edges in graph theory, key and values in data maps, and so
>> >> on. But
>> >> overall, specific names can get in the way.
>> >>
>> >> Perhaps what is missing from the Scala doc is context. Somehow, it
>> >> lists
>> >> together several methods but description is short, context can be
>> >> missing,
>> >> etc.
>> >>
>> >> I don't think the tradition of one letter type names will go away, but
>> >> in
>> >> a few entries of ScalaDoc I looked at, the types are (succinctly)
>> >> explained
>> >> in the Scala doc itself. So even if the names aren't very explicit, the
>> >> doc
>> >> is here.
>> >>
>> >> --
>> >> Philippe Lhoste
>> >> --  (near) Paris -- France
>> >> --  http://Phi.Lho.free.fr
>> >> --  --  --  --  --  --  --  --  --  --  --  --  --  --
>> >>
>> >
>> >
>

There are many useful blogs out there.  Tony's blog (1) contains many
good posts.  Most are in the form of exercises which I find way more
useful to learn from.  There is also Runars blog (2) with many useful,
descriptive posts.  Debasish Ghosh has a blog that contains a wealth
of information.  He has been learning all the FP concepts and
regularly posts when he has come to understand a concept.  Eric
Torreborre's (4) blog is similar.  One of my favorites of his is the
translation of "The Essence of the Iterator Pattern" into scala (5).
In truth, your best bet is to go to the original source material for
these concepts, many of which were created before scala.  You'll have
to learn a different language, but it's not a hard language.  In fact,
it's much much simpler than scala.  LYAH(6) is a great way to get
started with the language and will help introduce you to many of the
concepts in FP.  From there you can go to read the Typeclassopedia (7)
- which I found extremely helpful and would love to see someone
translate into scala. From there, you can follow the links to the
papers describing the concepts at depth.
These are the avenues that I used - and am still using! - to learn
about FP. My only complaint is that I didn't start learning this
stuff 10 years ago!

HTH,
Rich

(1) http://blog.tmorris.net/(2) http://apocalisp.wordpress.com/(3)
http://debasishg.blogspot.com/(4) http://etorreborre.blogspot.com/(5)
http://etorreborre.blogspot.com/2011/06/essence-of-iterator-pattern.html(6)
http://learnyouahaskell.com/
(7) http://www.haskell.org/wikiupload/8/85/TMR-Issue13.pdf
On Sat, Nov 19, 2011 at 8:36 PM, Russ Paielli wrote:
> This question has no doubt been asked and answered a hundred times, but
> which online Scala FP or Scalaz tutorial do you recommend? I'm looking for
> something that is (1) freely available online, (2) starts more or less with
> the basics of FP and goes from there (3) provides examples in Scala. Thanks.
>
> (Yes, I did a quick google on it, but the results do not appear to be
> particularly useful to me.)
>
> --Russ P.
>
>
> On Sat, Nov 19, 2011 at 7:05 PM, Tony Morris wrote:
>>
>> So well put Richard.
>>
>> The amount of damage that is done by perpetuating the myth that
>> understanding the subject matter at hand is somehow unapproachable by
>> speaking to all these logical fallacies is just sad. No I really want born
>> with categorytheory.so in my brain our whatever nonsense it may require to
>> continue justifying these myths (they astound me every time, so please
>> excuse my naive guessing).
>>
>> Fine, don't understand it, fine call me names, call me crazy or lacking
>> communication skills, use all the fallacies at your disposal. I DO NOT GIVE
>> A FUCK THAT YOU ARE WRONG AND I REFUSE TO TAKE YOUR BULLYING PERSONALLY.
>> But I do care that the next guy might fall for it. Thankfully Richard is not
>> one of those and has taught me a few things on occasion and will likely
>> continue to do so (thanks Richard).
>>
>> To others, beware of the trap, especially the illusion of comfort it
>> advertises. It's bullshit.
>>
>> On Nov 20, 2011 12:27 PM, "Richard Wallace"
>> wrote:
>>>
>>> Ken,
>>>
>>> The funniest - and saddest - thing in all of this is that Tony is
>>> trying very hard to dissuade you of the opinion that he is so
>>> brilliant!
>>>
>>> When I started with FP a few years ago I felt the same as you do now.
>>> It seemed complex.  Guys like Tony seemed uber smart and I thought I
>>> could never learn as much as they had.  But then I started learning
>>> the basic concepts, and the concepts that build on those, and so on.
>>> I realized just how wrong I was. Tony is a smart dude, maybe smarter
>>> than I am maybe not.  But he's certainly been around the FP block
>>> longer than I, and most other people, have been. So he's learned -
>>> really learned, not just glossed over the concepts like some people do
>>> - about FP and the concepts involved.  As I've seen him say in various
>>> other threads like this, it's not like he was born with this
>>> knowledge.
>>>
>>> You are hurting yourself - and I wish it was only yourself, but more
>>> on that in a second - by continuing to say, "Tony is so much smarter
>>> than me and everybody else, we can't possible ever understand all this
>>> stuff.  It's too complex!"  In fact, it's not complex at all.  It only
>>> looks that way to someone new to the concepts, much like calculus,
>>> linear algebra and differential equations look complex to someone just
>>> learning basic algebra.  But these are things that _everyone_ can come
>>> to understand given time and effort.
>>>
>>> If you don't want to put in the time and effort to learn these things,
>>> then fine.  But stop raising everyone who has taken the time and put
>>> in the effort up on a pedestal - yes, you are the one putting them
>>> there, they are not putting themselves there - and using that as an
>>> excuse for you not understanding!  You do them a disservice by saying
>>> that's it is some natural born gift that allows them to understand
>>> these things and - to retract what I said earlier - you perpetuate the
>>> myth to others, causing them to be scared away by these concepts!
>>> (When I was learning about monads the biggest thing I had to overcome
>>> was all the hype around them.  I understood the basics pretty quickly,
>>> but thought I was missing something because of all the blogs and
>>> people talking about how hard monads are to understand.  But they are
>>> the simplest things possible!)
>>>
>>> So please, please stop with this, "It's so complex and your so smart I
>>> can't possibly hope to understand this stuff the way you do,"
>>> nonsense.
>>>
>>> On Sat, Nov 19, 2011 at 6:20 PM, Kenneth McDonald
>>> wrote:
>>> >
>>> > Yes, because a very straight-forward and efficient answer is totally
>>> >>
>>> >> off-the-charts.
>>> >
>>> > As usual from you, you are spouting complete nonsense. If I were in
>>> > such an
>>> > interview, I would assume that my interviewer wanted to test my
>>> > understanding of basic data structures. (Your assumption seems to be
>>> > that
>>> > the interviewer's expectations are spread out across the Milky way). I
>>> > would
>>> > then return an answer consonant with these expectations, and be willing
>>> > to
>>> > answer further questions on the same topic if the interviewer wanted.
>>> > Tony, don't you freakin' get it? You are brilliant (good) but virtually
>>> > incapable of communicating with the rest of humanity who is below your
>>> > level
>>> > of brilliance. (This is bad. Don't ask me to go into why, if you don't
>>> > understand it, even a brain transplant won't help). As long as you
>>> > maintain
>>> > your pretense of "superiority" over the rest of us, you will achieve
>>> > almost
>>> > nothing. If you come to understand that the rest of us do not do things
>>> > the
>>> > way you do and never will, then you have a chance to make a real
>>> > contribution.
>>> > Just feedback from someone who would really like to read reasonable
>>> > tract
>>> > from you, but has never found one.
>>> > Ken
>
>
>
> --
> http://RussP.us
>

On Sun, Nov 20, 2011 at 9:55 AM, Richard Wallace <rwallace@thewallacepack.net> wrote:

On Sun, Nov 20, 2011 at 5:08 AM, Josh Suereth <joshua.suereth@gmail.com> wrote:
> My point is exactly that the documentation is *not* in the types.
>

But it is.  You're own example shows that.  What is so cryptic about
fmap[A, B](fa: F[A])(f: A => B): F[B]?

This exactly highlights the problem.  Although the types say _what happens_, they do not say _why you would want to do this_.

This also gets back to the reinventing Scalaz point; here I think I pretty much agree with Martin's utility-vs-effort point.  The reason why bits of Scalaz keep getting invented is not because it is hard but because it is easy.  However, _because_ it is easy to reinvent, the value of picking it up in an external library vs. just reinventing it yourself when you need it is rather small.  Thus, if you want the library to be maximally useful, you need to make it even easier to pick it up (i.e. you need documentation that allows people who do not already know they need the concept to understand what the concept is).

Also, there are all sorts of bits you might need, and all sorts of different ways to (re-)invent them.  If you have a F[A,B], your fmap isn't going to help you.  If you decide you need a g[A,B](xab: F[A,B])(f: A => C): F[C,B] or the equivalent for F[A,C] or F[C,D], you can just create it.  Or, when you're creating F to begin with, you can give it mapA and mapB methods.  Invent what you need.

I agree with you, Richard, that Scalaz is useful and is not hard _once you understand what is going on_.  Getting to that utility via the Scalaz way vs. your own efforts to abstract the patterns that appear in your code is not a clear win unless you can gain understanding relatively easily.  Otherwise, your effort may be better spent re-inventing the concepts that you most need.

The attitude of types-document seems to extend too far into the Scalaz library where the types do not, in fact, document.  Take FingerTree, for instance--this is a powerful non-obvious data structure that I might like to use in my own code without reinventing.  We start off with the abstract class with

sealed abstract class Finger[V, A] {
  def foldMap[B](f: A => B)(implicit m: Semigroup[B]): B
  def +:(a: => A): Finger[V, A]
  def :+(a: => A): Finger[V, A]
  def |-:(a: => A): Finger[V, A]
  def :-|(a: => A): Finger[V, A]

and are immediately confronted with three non-obvious puzzles: first, why does a container class have two type signatures instead of one?  V, A doesn't really help in the absence of documentation.  How is this different than an arbitrary F[A,B]?  Second, what is a semigroup, and why would a foldMap need one in order to extract a B from a Finger[V,A]?  Third, what do |-: and :-| do?--they have identical type signatures to +: and :+, which, fortunately, are documented in the Scala collections.

So we start with tantalizing performance characteristics but immediately get hit by a bunch of puzzles, only some of which can be solved via introspection.  Almost makes one want to settle for O(log n) instead of O(1), or spend a bit more time learning the finger tree algorithm and implement it from scratch in a higher-performance way.
 

I didn't say, "we want to remain useful." I said the focus is on being
useful, not on being widely used.  This means that we spend our time
adding new abstractions and utility.  I'd really like to see some of
the concepts described in scaladoc too.

But the "types document" line implies that if you can't figure out what V and A are from reading Finger[V,A], that you're somehow too impatient or suffer from some other deficiency.  It really doesn't help anything.  In a few cases, the types document.  In many more cases, they don't.  If you don't know what is going on, spending a bunch of time introspecting and coming up blank is not a very appealing prospect.

  --Rex

On Nov 20, 2011 10:22 PM, "Josh Suereth" <joshua.suereth@gmail.com> wrote:
>
> Tony -
>
> Scalaz didn't block just anyone from learning concepts,  it blocked me (someone who really wanted to learn these concepts)  until enough blogs and things are available.  I wound up learning haskell snce scalaz docs were so poor.  As chris said, you end up reinventing portions of scalaz at times.  I wouldn't do this if I had been able to understand what a type like ValidationNel was for before the blog posts were written.
>
> Category theory can be a useful way to compose behavior of functions.   It's like design patterns for FP but can be exposed directly. These are abstract concepts and hard to learn.  Scalaz does itself a disservice by providing poor documentation for those like me (not coming from Haskell.)
>
> I think you'll always have folks who find category theory too abstract, but the point is better documentation can help a lot of us learn.
>
> Back to the original point:   a name used in code is only as good as its definition.   Sometimes using a longer name for a type parameter means I can convey a better definition.   Sometimes it could be worse. 

Nobody has yet provided an example or coherent explanation. All I have heard are:

* yeah but you are crazy
* you are above average, what about the rest of us [who want to name things as they not]?
* you are wrong because I once had lunch with Simon Peyton-Jones

Perhaps you can demonstrate this elusive insight that I am charged with overlooking. Forgive me if the above arguments are as good as it can get.

Yes.  I've read all of these.  Lyah is good, I went through real world Haskell first.

Now, back to my point on complexity.

Scalaz is *abstract* not complex.
Scalaz has *poor direct documentation* (you have to read blogs or books on Haskell) and therefore has a steeper learning curve which makes people say "scalaz is complex ".

Scalaz actually has a great very helpful mailing list where you can learn things.  However when learning scalaz, the usual approaches of source and scaladoc are out for most until you understand a modicum of the features.

The debate is on whether this is complex.  My point is that a steeper learning curve is not complexity.  Scalaz is a poor example of complexity because the documentation is not where most of us look, and so learning curve and complexity are confused.

On Nov 20, 2011 10:26 AM, "Richard Wallace" <rwallace@thewallacepack.net> wrote:

There are many useful blogs out there.  Tony's blog (1) contains many
good posts.  Most are in the form of exercises which I find way more
useful to learn from.  There is also Runars blog (2) with many useful,
descriptive posts.  Debasish Ghosh has a blog that contains a wealth
of information.  He has been learning all the FP concepts and
regularly posts when he has come to understand a concept.  Eric
Torreborre's (4) blog is similar.  One of my favorites of his is the
translation of "The Essence of the Iterator Pattern" into scala (5).
In truth, your best bet is to go to the original source material for
these concepts, many of which were created before scala.  You'll have
to learn a different language, but it's not a hard language.  In fact,
it's much much simpler than scala.  LYAH(6) is a great way to get
started with the language and will help introduce you to many of the
concepts in FP.  From there you can go to read the Typeclassopedia (7)
- which I found extremely helpful and would love to see someone
translate into scala.  From there, you can follow the links to the
papers describing the concepts at depth.
These are the avenues that I used - and am still using! - to learn
about FP.  My only complaint is that I didn't start learning this
stuff 10 years ago!

HTH,
Rich

(1) http://blog.tmorris.net/(2) http://apocalisp.wordpress.com/(3)
http://debasishg.blogspot.com/(4) http://etorreborre.blogspot.com/(5)
http://etorreborre.blogspot.com/2011/06/essence-of-iterator-pattern.html(6)
http://learnyouahaskell.com/
(7) http://www.haskell.org/wikiupload/8/85/TMR-Issue13.pdf
On Sat, Nov 19, 2011 at 8:36 PM, Russ Paielli <russ.paielli@gmail.com> wrote:
> This question has no doubt been asked and answered a hundred times, but
> which online Scala FP or Scalaz tutorial do you recommend? I'm looking for
> something that is (1) freely available online, (2) starts more or less with
> the basics of FP and goes from there (3) provides examples in Scala. Thanks.
>
> (Yes, I did a quick google on it, but the results do not appear to be
> particularly useful to me.)
>
> --Russ P.
>
>
> On Sat, Nov 19, 2011 at 7:05 PM, Tony Morris <tmorris@tmorris.net> wrote:
>>
>> So well put Richard.
>>
>> The amount of damage that is done by perpetuating the myth that
>> understanding the subject matter at hand is somehow unapproachable by
>> speaking to all these logical fallacies is just sad. No I really want born
>> with categorytheory.so in my brain our whatever nonsense it may require to
>> continue justifying these myths (they astound me every time, so please
>> excuse my naive guessing).
>>
>> Fine, don't understand it, fine call me names, call me crazy or lacking
>> communication skills, use all the fallacies at your disposal. I DO NOT GIVE
>> A FUCK THAT YOU ARE WRONG AND I REFUSE TO TAKE YOUR BULLYING PERSONALLY.
>> But I do care that the next guy might fall for it. Thankfully Richard is not
>> one of those and has taught me a few things on occasion and will likely
>> continue to do so (thanks Richard).
>>
>> To others, beware of the trap, especially the illusion of comfort it
>> advertises. It's bullshit.
>>
>> On Nov 20, 2011 12:27 PM, "Richard Wallace" <rwallace@thewallacepack.net>
>> wrote:
>>>
>>> Ken,
>>>
>>> The funniest - and saddest - thing in all of this is that Tony is
>>> trying very hard to dissuade you of the opinion that he is so
>>> brilliant!
>>>
>>> When I started with FP a few years ago I felt the same as you do now.
>>> It seemed complex.  Guys like Tony seemed uber smart and I thought I
>>> could never learn as much as they had.  But then I started learning
>>> the basic concepts, and the concepts that build on those, and so on.
>>> I realized just how wrong I was. Tony is a smart dude, maybe smarter
>>> than I am maybe not.  But he's certainly been around the FP block
>>> longer than I, and most other people, have been. So he's learned -
>>> really learned, not just glossed over the concepts like some people do
>>> - about FP and the concepts involved.  As I've seen him say in various
>>> other threads like this, it's not like he was born with this
>>> knowledge.
>>>
>>> You are hurting yourself - and I wish it was only yourself, but more
>>> on that in a second - by continuing to say, "Tony is so much smarter
>>> than me and everybody else, we can't possible ever understand all this
>>> stuff.  It's too complex!"  In fact, it's not complex at all.  It only
>>> looks that way to someone new to the concepts, much like calculus,
>>> linear algebra and differential equations look complex to someone just
>>> learning basic algebra.  But these are things that _everyone_ can come
>>> to understand given time and effort.
>>>
>>> If you don't want to put in the time and effort to learn these things,
>>> then fine.  But stop raising everyone who has taken the time and put
>>> in the effort up on a pedestal - yes, you are the one putting them
>>> there, they are not putting themselves there - and using that as an
>>> excuse for you not understanding!  You do them a disservice by saying
>>> that's it is some natural born gift that allows them to understand
>>> these things and - to retract what I said earlier - you perpetuate the
>>> myth to others, causing them to be scared away by these concepts!
>>> (When I was learning about monads the biggest thing I had to overcome
>>> was all the hype around them.  I understood the basics pretty quickly,
>>> but thought I was missing something because of all the blogs and
>>> people talking about how hard monads are to understand.  But they are
>>> the simplest things possible!)
>>>
>>> So please, please stop with this, "It's so complex and your so smart I
>>> can't possibly hope to understand this stuff the way you do,"
>>> nonsense.
>>>
>>> On Sat, Nov 19, 2011 at 6:20 PM, Kenneth McDonald <ykkenmcd@gmail.com>
>>> wrote:
>>> >
>>> > Yes, because a very straight-forward and efficient answer is totally
>>> >>
>>> >> off-the-charts.
>>> >
>>> > As usual from you, you are spouting complete nonsense. If I were in
>>> > such an
>>> > interview, I would assume that my interviewer wanted to test my
>>> > understanding of basic data structures. (Your assumption seems to be
>>> > that
>>> > the interviewer's expectations are spread out across the Milky way). I
>>> > would
>>> > then return an answer consonant with these expectations, and be willing
>>> > to
>>> > answer further questions on the same topic if the interviewer wanted.
>>> > Tony, don't you freakin' get it? You are brilliant (good) but virtually
>>> > incapable of communicating with the rest of humanity who is below your
>>> > level
>>> > of brilliance. (This is bad. Don't ask me to go into why, if you don't
>>> > understand it, even a brain transplant won't help). As long as you
>>> > maintain
>>> > your pretense of "superiority" over the rest of us, you will achieve
>>> > almost
>>> > nothing. If you come to understand that the rest of us do not do things
>>> > the
>>> > way you do and never will, then you have a chance to make a real
>>> > contribution.
>>> > Just feedback from someone who would really like to read reasonable
>>> > tract
>>> > from you, but has never found one.
>>> > Ken
>
>
>
> --
> http://RussP.us
>

def f(p: Boolean): Int = ...

This function's type documents that it accepts one of two values and returns one of 2^32 values. Since functions represents exponentiation, we can easily compute that there are (2^32)^2 possible implementations of this function. The function definitely does not accept a String anywhere at any time, nor a Wibble or a Wobble and many other things and we are guaranteed the structure of the thing it returns. For example, that thing has only nullary constructors, among other properties.

This all assumes the function terminates and does not side-effect; both reasonable assumptions in practice.

Now take this reasoning and extrapolate it. In particular apply it to polymorphic functions where you get much more rigorous documentation, as explained by Philip Wadler.

Sometimes I wonder if you guys realise you're using a statically typed language.

On Nov 21, 2011 3:25 AM, "Rex Kerr" <ichoran@gmail.com> wrote:

On Sun, Nov 20, 2011 at 9:55 AM, Richard Wallace <rwallace@thewallacepack.net> wrote:

On Sun, Nov 20, 2011 at 5:08 AM, Josh Suereth <joshua.suereth@gmail.com> wrote:
> My point is exactly that the documentation is *not* in the types.
>

But it is.  You're own example shows that.  What is so cryptic about
fmap[A, B](fa: F[A])(f: A => B): F[B]?

This exactly highlights the problem.  Although the types say _what happens_, they do not say _why you would want to do this_.

This also gets back to the reinventing Scalaz point; here I think I pretty much agree with Martin's utility-vs-effort point.  The reason why bits of Scalaz keep getting invented is not because it is hard but because it is easy.  However, _because_ it is easy to reinvent, the value of picking it up in an external library vs. just reinventing it yourself when you need it is rather small.  Thus, if you want the library to be maximally useful, you need to make it even easier to pick it up (i.e. you need documentation that allows people who do not already know they need the concept to understand what the concept is).

Also, there are all sorts of bits you might need, and all sorts of different ways to (re-)invent them.  If you have a F[A,B], your fmap isn't going to help you.  If you decide you need a g[A,B](xab: F[A,B])(f: A => C): F[C,B] or the equivalent for F[A,C] or F[C,D], you can just create it.  Or, when you're creating F to begin with, you can give it mapA and mapB methods.  Invent what you need.

I agree with you, Richard, that Scalaz is useful and is not hard _once you understand what is going on_.  Getting to that utility via the Scalaz way vs. your own efforts to abstract the patterns that appear in your code is not a clear win unless you can gain understanding relatively easily.  Otherwise, your effort may be better spent re-inventing the concepts that you most need.

The attitude of types-document seems to extend too far into the Scalaz library where the types do not, in fact, document.  Take FingerTree, for instance--this is a powerful non-obvious data structure that I might like to use in my own code without reinventing.  We start off with the abstract class with

sealed abstract class Finger[V, A] {
  def foldMap[B](f: A => B)(implicit m: Semigroup[B]): B

  def +:(a: => A): Finger[V, A]
  def :+(a: => A): Finger[V, A]
  def |-:(a: => A): Finger[V, A]
  def :-|(a: => A): Finger[V, A]

and are immediately confronted with three non-obvious puzzles: first, why does a container class have two type signatures instead of one?  V, A doesn't really help in the absence of documentation.  How is this different than an arbitrary F[A,B]?  Second, what is a semigroup, and why would a foldMap need one in order to extract a B from a Finger[V,A]?  Third, what do |-: and :-| do?--they have identical type signatures to +: and :+, which, fortunately, are documented in the Scala collections.

So we start with tantalizing performance characteristics but immediately get hit by a bunch of puzzles, only some of which can be solved via introspection.  Almost makes one want to settle for O(log n) instead of O(1), or spend a bit more time learning the finger tree algorithm and implement it from scratch in a higher-performance way.
 

I didn't say, "we want to remain useful." I said the focus is on being
useful, not on being widely used.  This means that we spend our time
adding new abstractions and utility.  I'd really like to see some of
the concepts described in scaladoc too.

But the "types document" line implies that if you can't figure out what V and A are from reading Finger[V,A], that you're somehow too impatient or suffer from some other deficiency.  It really doesn't help anything.  In a few cases, the types document.  In many more cases, they don't.  If you don't know what is going on, spending a bunch of time introspecting and coming up blank is not a very appealing prospect.

  --Rex

So... a hypothetical example.
I have some particular problem to solve.  I ask around, perhaps on stack overflow, IRC and mailing lists.
I'm directed to an elegant-looking solution using scalaz, so I look at the scalaz home page and a couple of references also made in the answers.  They all, ultimately, redirect me to two or three academic papers, every one of which explains the concepts using Haskell as a reference language.
I've never learned Haskell and I know that I can solve my problem, less elegantly, using Scala constructs and libraries that I'm already familiar with.
This has to be finished soon, my deadline is next thursday, and I'm essentially being told that I must learn an entire other programming language in order to be able to understand and correctly apply the solution being advocated to me.
For me, as a working programmer, with very real time constraints and a family to pay for, scalaz is most definitely (if subjectively) too complex for my particular use-case.

If the tutorials were better (or even existed, in many cases), I could figure things out in time to apply the scalaz solution before my deadline.  I'd keep coming back to the library, constantly learning and applying it in ever more scenarios.  I *know* that I can and would do this, because it's the exact approach that led me to using Scala in the first place.
In the meantime, I'll keep paying my mortgage...

In reality, I *do* use scalaz on occasion, but I'm also very aware that the above scenario was all-too-recently my own.  I'm also even more aware that every bit of scalaz I use will have to be maintained by my colleagues, and that I don't have the time to be a personal tutor, so they'll have to go through the above pain barrier as well.



On 20 November 2011 18:51, Josh Suereth <joshua.suereth@gmail.com> wrote:

Yes.  I've read all of these.  Lyah is good, I went through real world Haskell first.

Now, back to my point on complexity.

Scalaz is *abstract* not complex.
Scalaz has *poor direct documentation* (you have to read blogs or books on Haskell) and therefore has a steeper learning curve which makes people say "scalaz is complex ".

Scalaz actually has a great very helpful mailing list where you can learn things.  However when learning scalaz, the usual approaches of source and scaladoc are out for most until you understand a modicum of the features.

The debate is on whether this is complex.  My point is that a steeper learning curve is not complexity.  Scalaz is a poor example of complexity because the documentation is not where most of us look, and so learning curve and complexity are confused.

On Nov 20, 2011 10:26 AM, "Richard Wallace" <rwallace@thewallacepack.net> wrote:

There are many useful blogs out there.  Tony's blog (1) contains many
good posts.  Most are in the form of exercises which I find way more
useful to learn from.  There is also Runars blog (2) with many useful,
descriptive posts.  Debasish Ghosh has a blog that contains a wealth
of information.  He has been learning all the FP concepts and
regularly posts when he has come to understand a concept.  Eric
Torreborre's (4) blog is similar.  One of my favorites of his is the
translation of "The Essence of the Iterator Pattern" into scala (5).
In truth, your best bet is to go to the original source material for
these concepts, many of which were created before scala.  You'll have
to learn a different language, but it's not a hard language.  In fact,
it's much much simpler than scala.  LYAH(6) is a great way to get
started with the language and will help introduce you to many of the
concepts in FP.  From there you can go to read the Typeclassopedia (7)
- which I found extremely helpful and would love to see someone
translate into scala.  From there, you can follow the links to the
papers describing the concepts at depth.
These are the avenues that I used - and am still using! - to learn
about FP.  My only complaint is that I didn't start learning this
stuff 10 years ago!

HTH,
Rich

(1) http://blog.tmorris.net/(2) http://apocalisp.wordpress.com/(3)
http://debasishg.blogspot.com/(4) http://etorreborre.blogspot.com/(5)
http://etorreborre.blogspot.com/2011/06/essence-of-iterator-pattern.html(6)
http://learnyouahaskell.com/
(7) http://www.haskell.org/wikiupload/8/85/TMR-Issue13.pdf
On Sat, Nov 19, 2011 at 8:36 PM, Russ Paielli <russ.paielli@gmail.com> wrote:
> This question has no doubt been asked and answered a hundred times, but
> which online Scala FP or Scalaz tutorial do you recommend? I'm looking for
> something that is (1) freely available online, (2) starts more or less with
> the basics of FP and goes from there (3) provides examples in Scala. Thanks.
>
> (Yes, I did a quick google on it, but the results do not appear to be
> particularly useful to me.)
>
> --Russ P.
>
>
> On Sat, Nov 19, 2011 at 7:05 PM, Tony Morris <tmorris@tmorris.net> wrote:
>>
>> So well put Richard.
>>
>> The amount of damage that is done by perpetuating the myth that
>> understanding the subject matter at hand is somehow unapproachable by
>> speaking to all these logical fallacies is just sad. No I really want born
>> with categorytheory.so in my brain our whatever nonsense it may require to
>> continue justifying these myths (they astound me every time, so please
>> excuse my naive guessing).
>>
>> Fine, don't understand it, fine call me names, call me crazy or lacking
>> communication skills, use all the fallacies at your disposal. I DO NOT GIVE
>> A FUCK THAT YOU ARE WRONG AND I REFUSE TO TAKE YOUR BULLYING PERSONALLY.
>> But I do care that the next guy might fall for it. Thankfully Richard is not
>> one of those and has taught me a few things on occasion and will likely
>> continue to do so (thanks Richard).
>>
>> To others, beware of the trap, especially the illusion of comfort it
>> advertises. It's bullshit.
>>
>> On Nov 20, 2011 12:27 PM, "Richard Wallace" <rwallace@thewallacepack.net>
>> wrote:
>>>
>>> Ken,
>>>
>>> The funniest - and saddest - thing in all of this is that Tony is
>>> trying very hard to dissuade you of the opinion that he is so
>>> brilliant!
>>>
>>> When I started with FP a few years ago I felt the same as you do now.
>>> It seemed complex.  Guys like Tony seemed uber smart and I thought I
>>> could never learn as much as they had.  But then I started learning
>>> the basic concepts, and the concepts that build on those, and so on.
>>> I realized just how wrong I was. Tony is a smart dude, maybe smarter
>>> than I am maybe not.  But he's certainly been around the FP block
>>> longer than I, and most other people, have been. So he's learned -
>>> really learned, not just glossed over the concepts like some people do
>>> - about FP and the concepts involved.  As I've seen him say in various
>>> other threads like this, it's not like he was born with this
>>> knowledge.
>>>
>>> You are hurting yourself - and I wish it was only yourself, but more
>>> on that in a second - by continuing to say, "Tony is so much smarter
>>> than me and everybody else, we can't possible ever understand all this
>>> stuff.  It's too complex!"  In fact, it's not complex at all.  It only
>>> looks that way to someone new to the concepts, much like calculus,
>>> linear algebra and differential equations look complex to someone just
>>> learning basic algebra.  But these are things that _everyone_ can come
>>> to understand given time and effort.
>>>
>>> If you don't want to put in the time and effort to learn these things,
>>> then fine.  But stop raising everyone who has taken the time and put
>>> in the effort up on a pedestal - yes, you are the one putting them
>>> there, they are not putting themselves there - and using that as an
>>> excuse for you not understanding!  You do them a disservice by saying
>>> that's it is some natural born gift that allows them to understand
>>> these things and - to retract what I said earlier - you perpetuate the
>>> myth to others, causing them to be scared away by these concepts!
>>> (When I was learning about monads the biggest thing I had to overcome
>>> was all the hype around them.  I understood the basics pretty quickly,
>>> but thought I was missing something because of all the blogs and
>>> people talking about how hard monads are to understand.  But they are
>>> the simplest things possible!)
>>>
>>> So please, please stop with this, "It's so complex and your so smart I
>>> can't possibly hope to understand this stuff the way you do,"
>>> nonsense.
>>>
>>> On Sat, Nov 19, 2011 at 6:20 PM, Kenneth McDonald <ykkenmcd@gmail.com>
>>> wrote:
>>> >
>>> > Yes, because a very straight-forward and efficient answer is totally
>>> >>
>>> >> off-the-charts.
>>> >
>>> > As usual from you, you are spouting complete nonsense. If I were in
>>> > such an
>>> > interview, I would assume that my interviewer wanted to test my
>>> > understanding of basic data structures. (Your assumption seems to be
>>> > that
>>> > the interviewer's expectations are spread out across the Milky way). I
>>> > would
>>> > then return an answer consonant with these expectations, and be willing
>>> > to
>>> > answer further questions on the same topic if the interviewer wanted.
>>> > Tony, don't you freakin' get it? You are brilliant (good) but virtually
>>> > incapable of communicating with the rest of humanity who is below your
>>> > level
>>> > of brilliance. (This is bad. Don't ask me to go into why, if you don't
>>> > understand it, even a brain transplant won't help). As long as you
>>> > maintain
>>> > your pretense of "superiority" over the rest of us, you will achieve
>>> > almost
>>> > nothing. If you come to understand that the rest of us do not do things
>>> > the
>>> > way you do and never will, then you have a chance to make a real
>>> > contribution.
>>> > Just feedback from someone who would really like to read reasonable
>>> > tract
>>> > from you, but has never found one.
>>> > Ken
>
>
>
> --
> http://RussP.us
>

--
Kevin Wright
mail: kevin.wright@scalatechnology.com
gtalk / msn : kev.lee.wright@gmail.com quora: http://www.quora.com/Kevin-Wrightgoogle+: http://gplus.to/thecoda
kev.lee.wright@gmail.com twitter: @thecoda
vibe / skype: kev.lee.wrightsteam: kev_lee_wright
"My point today is that, if we wish to count lines of code, we should not regard them as "lines produced" but as "lines spent": the current conventional wisdom is so foolish as to book that count on the wrong side of the ledger" ~ Dijkstra

On Sunday 20 November 2011, Tony Morris wrote:
> def f(p: Boolean): Int = ...
>
> This function's type documents that it accepts one of two values and
> returns one of 2^32 values. Since functions represents
> exponentiation, we can easily compute that there are (2^32)^2
> possible implementations of this function. The function definitely
> does not accept a String anywhere at any time, nor a Wibble or a
> Wobble and many other things and we are guaranteed the structure of
> the thing it returns. For example, that thing has only nullary
> constructors, among other properties.
>
> This all assumes the function terminates and does not side-effect;
> both reasonable assumptions in practice.

Isn't referential transparency the salient condition? Namely, that the
function uses only its argument(s) in computing its result.

In the past, the most common appeal I recall to the argument about how
many implementations a given signature admits is that the putative
implementations have access to arbitrary information not included in
their arguments.

I think there are relatively few key criteria that need be elucidated to
forestall illogical / invalid reasoning about how functional programs
behave.

> ...

Randall Schulz

Wadler's free theorems paper assumeS referentially transparent
functions. I guess Tony does too. However, I don't see why
parametricity should imply one-letter type variable names. Not knowing
anything about a type doesn't prevent you from giving the type a name
that explains what your function does with values of this type.

For instance, the function first:

def first[A,B](x:A, y:B) : A

could feature these type variable names:

def first[TheTypeOfWhatsKept,TheTypeOfWhatsThrownAway](...): ...

These type names are ridiculously long but this is only to make my point.

Paul

On Sun, Nov 20, 2011 at 21:44, Randall R Schulz wrote:
> On Sunday 20 November 2011, Tony Morris wrote:
>> def f(p: Boolean): Int = ...
>>
>> This function's type documents that it accepts one of two values and
>> returns one of 2^32 values. Since functions represents
>> exponentiation, we can easily compute that there are (2^32)^2
>> possible implementations of this function. The function definitely
>> does not accept a String anywhere at any time, nor a Wibble or a
>> Wobble and many other things and we are guaranteed the structure of
>> the thing it returns. For example, that thing has only nullary
>> constructors, among other properties.
>>
>> This all assumes the function terminates and does not side-effect;
>> both reasonable assumptions in practice.
>
> Isn't referential transparency the salient condition? Namely, that the
> function uses only its argument(s) in computing its result.
>
> In the past, the most common appeal I recall to the argument about how
> many implementations a given signature admits is that the putative
> implementations have access to arbitrary information not included in
> their arguments.
>
> I think there are relatively few key criteria that need be elucidated to
> forestall illogical / invalid reasoning about how functional programs
> behave.
>
>
>> ...
>
>
> Randall Schulz
>

On 11/21/2011 06:50 AM, Paul Brauner wrote:
> Wadler's free theorems paper assumeS referentially transparent
> functions. I guess Tony does too.

Yes I do. It is a very reasonable assumption and one that I am quite
positive underpins this entire discussion.

> However, I don't see why
> parametricity should imply one-letter type variable names.

It is not so much one-letter type variable names, but that they do not
invite the projection of meaning that is not there, and we have seen
examples of this on this very thread.

> Not knowing
> anything about a type doesn't prevent you from giving the type a name
> that explains what your function does with values of this type.
>
> For instance, the function first:
>
> def first[A,B](x:A, y:B) : A
>
> could feature these type variable names:
>
> def first[TheTypeOfWhatsKept,TheTypeOfWhatsThrownAway](...): ...
>
> These type names are ridiculously long but this is only to make my point.

There is no need to document this function. It has only one possible
implementation. By specifying "what is kept" and "what is not", you are
only telling me what I already have a proof of. It says exactly that
*right there in the types and quantifiers of those types*. Don't
believe me? Go right ahead and provide an alternative implementation
that satisfies our reasonable assumptions.

The function does this:
def first[A, B](x: A, y: B): A = x

It is not possible for a function to do anything but this.

Therefore, all you have done is invited me to trust you over the
mechanical verifier (I don't), and even if I did, you have given me a
laborious means by which to derive the same conclusion.

I hope the point is starting to become clear to at least one person (and
I know there are some for which it is already clear).

On Sun, Nov 20, 2011 at 22:10, Tony Morris wrote:
> On 11/21/2011 06:50 AM, Paul Brauner wrote:
>> Wadler's free theorems paper assumeS referentially transparent
>> functions. I guess Tony does too.
>
> Yes I do. It is a very reasonable assumption and one that I am quite
> positive underpins this entire discussion.
>
>
>> However, I don't see why
>> parametricity should imply one-letter type variable names.
>
> It is not so much one-letter type variable names, but that they do not
> invite the projection of meaning that is not there, and we have seen
> examples of this on this very thread.
>
>> Not knowing
>> anything about a type doesn't prevent you from giving the type a name
>> that explains what your function does with values of this type.
>>
>> For instance, the function first:
>>
>>   def first[A,B](x:A, y:B) : A
>>
>> could feature these type variable names:
>>
>>   def first[TheTypeOfWhatsKept,TheTypeOfWhatsThrownAway](...): ...
>>
>> These type names are ridiculously long but this is only to make my point.
>
> There is no need to document this function. It has only one possible
> implementation. By specifying "what is kept" and "what is not", you are
> only telling me what I already have a proof of. It says exactly that
> *right there in the types and quantifiers of those types*.  Don't
> believe me? Go right ahead and provide an alternative implementation
> that satisfies our reasonable assumptions.
>

I was afraid you were going to say that... I just picked this one
because it is simple. Just take another example for which there's not
only one inhabitant of the type, like map.

> The function does this:
> def first[A, B](x: A, y: B): A = x
>
> It is not possible for a function to do anything but this.
>
> Therefore, all you have done is invited me to trust you over the
> mechanical verifier (I don't), and even if I did, you have given me a
> laborious means by which to derive the same conclusion.
>
> I hope the point is starting to become clear to at least one person (and
> I know there are some for which it is already clear).
>
> --
> Tony Morris
> http://tmorris.net/
>
>
>

On Sun, Nov 20, 2011 at 2:00 PM, Tony Morris <tmorris@tmorris.net> wrote:

def f(p: Boolean): Int = ...

This function's type documents that it accepts one of two values and returns one of 2^32 values. Since functions represents exponentiation, we can easily compute that there are (2^32)^2 possible implementations of this function.

Sure.  But that's not adequate documentation.  Maybe I want to know which of those 18-odd quintillion different functions I'm using, eh?  Of course types provide _some_ documentation, but that doesn't mean they provide _adequate_ documentation to solve problems.  Here's a better example:

class UnsignedInt24 {
  // ...
  def +(u: UnsignedInt24): UnsignedInt24
  // ...
}

There are (2^24)^(2^24) possible implementations of this method given the types.  I bet, given how I've named it, you can narrow down the possibilities to two.  But this only works because I have built upon an extremely well-understood operation.  If I had not, documentation (or reading source code) would have been essential for understanding what was going on and/or how to use it.

That's the issue.  Insisting that Scalaz is "self-documenting" because of the types is simply bad PR because in the interesting instances, those cases where Scalaz really would save you a lot of time an effort, the types are almost always not nearly enough.  So even if you're not daunted by the use of |+| and *->*->*, if the comments do not reflect what methods do beyond what the type signatures tell you, it's insufficient documentation.  (Even in those rare cases where the types *do* say everything there is to be said, an explanation of the consequences of these types can save a lot of staring and puzzling.)  Better to just admit it than risk making people feel stupid because they can't intuit from staring at types what :-| does, except express how they feel about Scalaz.

Scala's core library has had similar problems, though they are increasingly being solved.

Now, I'm not saying that solving this problem is easy.  If I ever release my muple library, it's almost certainly going to suffer from the same problem even though it's minuscule compared to the Scala library or Scalaz.  I'm almost certainly going to spend my time writing more code instead of improving the documentation beyond a basic level.  But I'm not going to pretend that it's not *my* fault that picking it up is harder than it should be in an ideal world where I had infinite time.

  --Rex
 

On 11/21/2011 08:12 AM, Rex Kerr wrote:

CAP_xLa0PjqCco2Gx7ziTUOy7PruPohc3pa9o0Q0FxPiC_DDmaQ [at] mail [dot] gmail [dot] com" type="cite"> On Sun, Nov 20, 2011 at 2:00 PM, Tony Morris <tmorris [at] tmorris [dot] net" rel="nofollow">tmorris@tmorris.net> wrote:

def f(p: Boolean): Int = ...

This function's type documents that it accepts one of two values and returns one of 2^32 values. Since functions represents exponentiation, we can easily compute that there are (2^32)^2 possible implementations of this function.

Sure.  But that's not adequate documentation.  Maybe I want to know which of those 18-odd quintillion different functions I'm using, eh?  Of course types provide _some_ documentation, but that doesn't mean they provide _adequate_ documentation to solve problems.  Here's a better example:

I agree. If types provided adequate documentation at all times, then I wouldn't have alluded to the mountains of other documentation for scalaz. What scalaz does do however, is significantly reduce ambiguity by using much more rigorous and efficient mechanisms of documentation, including thorough exploitation of scala's type system (which is a consequence of what attracts all this protest, which looks quite funny). I am only tipping the iceberg here.

Nevertheless, I don't care so much about scalaz. I do care about documentation and so do others it seems, despite their misdirected enthusiasm. I strongly encourage the learning of methods of documentation that are both very rigorous in their dependability for correctness and efficiency of coverage i.e. little effort on behalf of the documentation implementor while also conveying a relatively large amount of information. That this documentation goes passed the ears of a lot of people doesn't mean it's not there.

Here is another example to get the thinkers on and the blinkers off:

def reverse[A](a: List[A]): List[A]

Now the naming people are going to say, "it reverse a list!" by its very name. Bollocks I say; you've just extrapolated a conclusion on awfully weak evidence. I want stronger evidence and I want it now; not after reading 200 pages of ranting.

How many possible implementations are there with that type? Right now, assuming that List can go on forever, there are infinity. Gasp! That's way too many to disambiguate!

But then I said:

* reverse(Nil) == Nil
* forall x. reverse(List(x)) == List(x)

OK, so now there are fewer possible implementations to consider, but still way too many. So I said, right, no worries then:

* forall x y. reverse(x ::: y) == reverse(y) ::: reverse(x)

Now, I don't need to "say" these things. I can write them all in Scala using ScalaCheck. I won't have a proof of their correctness, but I will have *very strong evidence* for *very little effort*.

And guess what? If my documentation is correct; that these properties do hold, then there is only one possible implementation of that function; it reverses the list argument. There is absolutely no question about this on the stated premises. Much better than appealing to names and English now innit? Checkmate adocumentationists.

Now, all of this ability to reason efficiently and reliably disappears if we hadn't been polymorphic in our type:

def reverse(n: List[Int]): List[Int]

Now it's much more difficult to document, but still very possible. Think about achieving the same goal here. Why would you impose this on yourself anyway? Exactly, and this is all scalaz does -- is take this very thesis to an extreme without sacrifice on practical application for other incidentals.

Hopefully, truly hopefully, the fog is clearing somewhere in this world.

-- 
Tony Morris
http://tmorris.net/

Types provide a modicum of useful documentation, but are not good enough stopping point IMHO.

Also, it's useful to recognize that scala is OO with potential deep nesting such that reverse is defined on an object and can use its state, or any value in its scope.  A method is not a standalone unit.

On Nov 20, 2011 5:42 PM, "Tony Morris" <tonymorris@gmail.com> wrote:

On 11/21/2011 08:12 AM, Rex Kerr wrote:

On Sun, Nov 20, 2011 at 2:00 PM, Tony Morris <tmorris@tmorris.net> wrote:

def f(p: Boolean): Int = ...

This function's type documents that it accepts one of two values and returns one of 2^32 values. Since functions represents exponentiation, we can easily compute that there are (2^32)^2 possible implementations of this function.

Sure.  But that's not adequate documentation.  Maybe I want to know which of those 18-odd quintillion different functions I'm using, eh?  Of course types provide _some_ documentation, but that doesn't mean they provide _adequate_ documentation to solve problems.  Here's a better example:

I agree. If types provided adequate documentation at all times, then I wouldn't have alluded to the mountains of other documentation for scalaz. What scalaz does do however, is significantly reduce ambiguity by using much more rigorous and efficient mechanisms of documentation, including thorough exploitation of scala's type system (which is a consequence of what attracts all this protest, which looks quite funny). I am only tipping the iceberg here.

Nevertheless, I don't care so much about scalaz. I do care about documentation and so do others it seems, despite their misdirected enthusiasm. I strongly encourage the learning of methods of documentation that are both very rigorous in their dependability for correctness and efficiency of coverage i.e. little effort on behalf of the documentation implementor while also conveying a relatively large amount of information. That this documentation goes passed the ears of a lot of people doesn't mean it's not there.

Here is another example to get the thinkers on and the blinkers off:

def reverse[A](a: List[A]): List[A]

Now the naming people are going to say, "it reverse a list!" by its very name. Bollocks I say; you've just extrapolated a conclusion on awfully weak evidence. I want stronger evidence and I want it now; not after reading 200 pages of ranting.

How many possible implementations are there with that type? Right now, assuming that List can go on forever, there are infinity. Gasp! That's way too many to disambiguate!

But then I said:

* reverse(Nil) == Nil
* forall x. reverse(List(x)) == List(x)

OK, so now there are fewer possible implementations to consider, but still way too many. So I said, right, no worries then:

* forall x y. reverse(x ::: y) == reverse(y) ::: reverse(x)

Now, I don't need to "say" these things. I can write them all in Scala using ScalaCheck. I won't have a proof of their correctness, but I will have *very strong evidence* for *very little effort*.

And guess what? If my documentation is correct; that these properties do hold, then there is only one possible implementation of that function; it reverses the list argument. There is absolutely no question about this on the stated premises. Much better than appealing to names and English now innit? Checkmate adocumentationists.

Now, all of this ability to reason efficiently and reliably disappears if we hadn't been polymorphic in our type:

def reverse(n: List[Int]): List[Int]

Now it's much more difficult to document, but still very possible. Think about achieving the same goal here. Why would you impose this on yourself anyway? Exactly, and this is all scalaz does -- is take this very thesis to an extreme without sacrifice on practical application for other incidentals.

Hopefully, truly hopefully, the fog is clearing somewhere in this world.

-- 
Tony Morris
http://tmorris.net/

On Sun, Nov 20, 2011 at 11:42 PM, Tony Morris wrote:
> * forall x y. reverse(x ::: y) == reverse(y) ::: reverse(x)

OTOH, there is no way you can be reasonably productive if you need to
do the kind of deduction required read this property and be confident
that it the one you need.

I would guess that what really happens is that you study this property
once or twice until you are confident. Then you memorize that the
function named "reverse" in fact has this property, and what this
property means for the applicability of that function.

The next time you need to reverse a list you will rely on your memory,
and not the ScalaCheck enforced test, to select this function as a
solution and move on.

I believe that it is an accepted fact that memory is a very poor
evidence for what is actually true.

So in reality you choose either to believe that your recollection of
verifying the function property is correct, or you can choose to
believe that the person who named it "reverse" did the same
verification for you and manage to pick a reasonably intelligent name
to communicate this fact to you.

BR,
John