Having worked through this for java.jdbc (and to a lesser extent for CongoMongo), I think that I would approach it slightly differently in future:
Provide two functions: one taking a map, one taking keyword arguments; the
latter delegating to the former via & {:as opts} and then internal calls can
easily use the map-based argument approach.
One of the additional complexities in java.jdbc (as it stands today) is that
several functions accept an arbitrary number of arguments, followed by optional
keyword arguments as well, so several functions have to parse their argument
lists at runtime. Simplifying that to use a sequence (of current arguments)
followed by a map (of options) would make several things easier inside the
library, removing a lot of apply calls, as well as providing an API that is
more amenable to dynamic call construction...
I still think the keyword argument approach is far more readable to _users_ -
and it's also what was recommended in the Clojure Library Guidelines right up
until a few days ago:
http://dev.clojure.org/pages/viewpage.action?pageId=9142444
Reid McKenzie changed it on April 24th, completely reversing the previous
recommendation from "Unroll optional named arguments" to "Don't unroll optional
named arguments" - compare version 6 (from Stuart Halloway) with Reid's edits
in versions 7-11:
http://dev.clojure.org/pages/diffpagesbyversion.action?pageId=1573132&selectedPageVersions=11&selectedPageVersions=6
Sean
On Apr 25, 2014, at 3:41 PM, Colin Fleming <colin.mailingl...@gmail.com> wrote:
> Hi all,
>
> I'm working on an API at the moment, and I'm balancing whether to use inline
> keyword args which I would destructure in the functions, or whether to just
> pass an explicit params map as the last parameter. Comparison of the two
> options in case I'm not explaining myself well:
>
> Kwargs:
> (class/create-class :instance list
> :description "My description"
> :implements (keys class-methods)
> :methods (calculate-my-methods))
>
> Map:
> (class/create-class {:instance list
> :description "My description"
> :implements (keys class-methods)
> :methods (calculate-my-methods)})
>
> A lot of APIs I've seen have favoured kwargs, and it undeniably makes for
> some pretty code - Seesaw is the best example I've seen here, the API is a
> thing of beauty. However it seems to me to have some issues:
> If I want to delegate to another call from within an API function and use the
> same arguments, it's really awkward: (apply delegate (mapcat identity args))
> or some similarly awful black juxt magic. Or of course writing out all the
> parameters again, but that's even worse.
> It's more difficult to make parameters optional based on some runtime
> criteria since the params are baked into the function call. I guess this is
> usually dealt with by making the calls handle nil for a particular parameter.
> Both of these are much easier when passing an explicit map. Any preferences
> here, from either writing or using APIs like this?
>
> Cheers,
>
> Colin
>
>
> --
> 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
> ---
> You received this message because you are subscribed to the Google Groups
> "Clojure" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to clojure+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
Sean Corfield -- (904) 302-SEAN
An Architect's View -- http://corfield.org/
"Perfection is the enemy of the good."
-- Gustave Flaubert, French realist novelist (1821-1880)
signature.asc
Description: Message signed with OpenPGP using GPGMail
