DevoxxUK Lambdas Lab

[Richard Warburton]

> I realize that the state of the documentation is currently woefully
> inadequate.  My question at this point is: is that our biggest problem at
> this point?  (If so, that would be a good thing.)
>

I guess what I was really trying to say was I wouldn't worry about people
not initially looking at the Collectors class in order to find reducingBy,
because that's the kind of thing that's probably going to change once they
see a few examples.  I'm not sure that's the biggest remaining problem
though, see the end for comments on complexity.  The other big, unresolved,
issue is the complexity of type signatures on classes like Collectors.
 Many developers are happy with generics to the extent of "List<String>
means a list of strings", won't ever write "? extends Foo" let alone
something like "class Bar<T extends Bar>".  Those people are going to be
utterly confused by types on the Collectors class.

I accept that you can't really change generics the language feature at this
stage.  I'm also very glad that override rules are relatively simple.  For
what its worth, equals/hashcode overriding hasn't been an issue in
hackdays.  What I suspect you have the time to look at further is the error
messages that javac emits.  I appreciate that these have already improved
quite a bit in 8 over 7 but its an area that still has wins in terms of
improvement.  If you look at the Clang Diagnostics page -
http://clang.llvm.org/diagnostics.html - especially the sections "Fix-it
hints" and "Template Type Diffing" then you'll see what I'm getting at,
albeit in a C++ context.  These aren't changes to the type inference or
checking algorithms, just presenting information to the user in a clearer
manner.

We've been struggling without how to present and document these complicated
> and tangled concepts in Javadoc, and its not easy.  (It would be much
> easier to document a "dumbed down" API.)  So, let me turn the question
> around: what else can we be doing to best help people make the conceptual
> leaps required?


One thing that I've noticed with collections is that there is a lot of
descriptive text and not a lot of visual representations.  Given how many
people understand/learn better using images or with the help of images this
is quite important.  There is precedent in other areas which can be drawn
upon here.  Here are some ideas.

1. Represent FunctionalInterfaces using the same kind of small box, inputs
going in, outputs going out, images that you see in eip.  Eg:
http://www.eaipatterns.com/img/RoutingPatternsDecisionTree.gif

2. Most Higher Order Functions can be represented visually as well, here is
an example from the wikipedia page for fold:
http://upload.wikimedia.org/wikipedia/commons/3/3e/Right-fold-transformation.png

3. Perhaps try to think about a decision flow chart for common problems.
 Here is an example in terms of C++ STL Containers:
http://adrinael.net/containerchoice.png.  In this case I'm not talking
about the leaf nodes of the decision tree being collection types, but
higher order functions or Collectors.

I tested the hypothetical that this documentation was in place by pointing
>
>> two attendees of the lab, who had successfully solved the easier
>> exercises,
>> in its direction.  They still didn't produce "reducing(s -> 1,
>> Integer::sum)".  I'm honestly quite sceptical that people would make that
>> leap.  I don't think many developers when asked "produce something that
>> collects the count of a list" Will intuitively go in the direction of:
>>
>> [ "dad", "dad", "dad" ] -> [1, 1, 1] -> 3
>>
>
> Like many other things, this is only obvious in hindsight :(  Once you see
> the trick, its completely obvious and cool and you are unlikely to forget
> it.  (It's also extremely efficient and parallelizes well.)  So, how do we
> get people over that hump?  Or, is the problem worse, and you have
> concluded that the APIs are just "too advanced" for Java users?


I don't think the concept of a collector is too advanced for a Java
Developer, but its perhaps the kind of situation where people shouldn't be
expected to understand all the corner cases around a collector until
they've levelled up.  In that vein I would suggest that there are more
utility methods on the collectors class.  Counting is an example from this
thread.  That way people who don't need the full power of a Collector also
don't bear the conceptual burden, but it still leaves in place the more
advanced features that you've implemented and which will be useful for
advanced developers.

I also repeat my statement that despite this thread having a problem-filled
tone, I think in general JSR 335 has done a good job overall.  To my mind
the hackdays have already established that the "easy problems" are "easy to
implement" and I completely think that this is a far greater achievement
than it sounds when you write it in an email.

regards,

  Richard Warburton

  http://insightfullogic.com
  @RichardWarburto <http://twitter.com/richardwarburto>