DevoxxUK Lambdas Lab (original) (raw)

Richard Warburton richard.warburton at gmail.com
Wed Apr 3 14:03:03 PDT 2013

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 means a list of strings", won't ever write "? extends Foo" let alone something like "class 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>

More information about the lambda-dev mailing list