On Fri, 2 Jul 2010 07:50:45 -0700 (PDT)
Meikel Brandmeyer <m...@kotka.de> wrote:
> On Jul 2, 12:18 pm, Walter van der Laan <waltervanderl...@gmail.com>
> wrote:
> > For example you can point your browser
> > athttp://getclojure.org:8080/examples/reduce
> > for reduce examples.
> Is it necessary to have >250 examples for a function which has
> effectively five variations?
> (reduce + [])
> (reduce + [1])
> (reduce + [1 2 3])
> (reduce + 0 [])
> (reduce + 0 [1 2 3])
Seconded.
> I'm all for examples, but please: clear examples focusing on the thing
> being demonstrated. Symbol calling or showing that [1 2 3] and (list 1
> 2 3) can be interchanged in the example above are nice to know, but
> don't help to understand reduce itself. They should go to their own
> sections in a tutorial.
Yes. Symbol calling and the equivalence of [1 2 3] and '(1 2 3) aren't
really relevant to what reduce can do. Nor is showing someone how to
extract the arglist from a functions metadata.
While I think the effort is marvelous, some thought should go into the
purpose. That page looks like the purpose is to show off the
cleverness of the person who wrote it. As such, this page is probably
more confusing than helpful.
> PS: I also think the examples should demonstrate idiomatic clojure. [1
> 2 3] is idiomatic while '(1 2 3) is not. Whatever we put in examples
> will show up in code. So be it [] vs. '() or (.java interop) vs. (.
> interop (java)) - we should pay attention!
Ditto.
Examples are read in order, and should be presented from simple to
more complex. In particular, the first example shouldn't require
knowing anything but clojure syntax. Each further example should
introduce at most one new concept, reinforce the previous example
(though that should be kept to a minimum), or show the function
working on different data types - if they're not doing one of those
things, why are they there? All the inputs to an example should be
either literals, or the result of a simple function invocation. If the
user has to work to figure out what the input is, they're that much
more likely to skip the example, or - even worse - come up with the
wrong input and hence wrong result. Finally, maybe provide one example
(short) that might be considered a "real world" use.
They really need to include an explanation. Having the expected
results there would be nice as well.
> The 0.02€ of a guy who has not put effort in creating examples for the
> core API.
Not wanting to be that guy (no offense intended to Meikel, he made a
good point), here's what I think is a nice set of reduce examples:
; sum of 0 through 10: 45
(reduce + (range 10))
; Divide 1 by 2 and then 3: 1/6
(reduce / 1 [2 3])
; Build a set from a collection: #{:a :c :b}
(reduce conj #{} [:a :b :c])
; Build a sorted set from multiple collections: #{1 2 3 4 5 6}
(reduce into (sorted-set) [[3 1 2] [5 4 6]])
; Reverse a list: (3 2 1)
(reduce #(cons %2 %1) [] [1 2 3])
; Build a hash-map from n to n squared:
; {0 0, 1 1, 2 4, 3 9, 4 16, 5 25, 6 36, 7 49, 8 64, 9 81}
(reduce #(assoc %1 %2 (* %2 %2)) {} (range 10))
; Edge case with one argument: returns argument -> 2
(reduce conj [2])
; Edge case with one argument: returns argument -> 1
(reduce conj 1 [])
; Note that in the previous two examples, conj is not invoked, as it
; always returns a sequence.
; Edge case with no arguments: (*) -> 1
(reduce * [])
; Broken edge case: Wrong number of arguments passed to function:
(reduce conj [])
--
Mike Meyer <m...@mired.org> http://www.mired.org/consulting.html
Independent Network/Unix/Perforce consultant, email for more information.
O< ascii ribbon campaign - stop html mail - www.asciiribbon.org
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
