Good discussion, Greg. I'll add my two cents, point by point:
> * The documentation is sparse and the code is not self-documenting.
I've occasionally had some trouble in this area, but I actually do find
that it's not too hard to map from the Java AWS api directly to clojure.
For example, this cloudwatch request using Java API is fairly trivial to
map to Amazonica API:
cwClient = new ...;
request = new ListMetricsRequest();
request.setNamespace("foo");
cwClient.listMetrics(request);
Amazonica:
(def aws-creds {...})
cw/list-metrics(aws-creds :namespace "foo")
I believe this is only possible because of the high degree of uniformity
(although with a few exceptions) in the original Amazon API.
On the other hand, maybe it would be possible to auto-generate
comprehensive docs using the same Reflection techniques to discover the
methods in the java API. Perhaps a clojure script that can be run to
generate static doc files (Markdown or whatever).
> * Dynamically generating an API doesn't save anyone time
I suspect this is not true. The Amazon API is huge and new services are
being introduced all the time. Hand coding wrappers to create a
comprehensive API would be a huge task. Which is probably why no one else
has done it--- at best one provider supports 2 or 3 AWS services in a
single API.
The comprehensive nature of the Amazonica API is it's big win-- no need to
find and learn multiple libraries (one for each AWS service).
> * Functions are both variadic and dispatch on argument type
I agree with this one. Inline keyword args often lead to trouble, where an
options Map while slightly more characters to type is usually simpler.
> * There are no releases or tags on github
My company is not strict about this, so I don't experience this problem.
But I do sympathize with the request, and tags would also be helpful when
trying to debug or better understand how the particular version we are
using works.
marc
On Thu, Nov 20, 2014 at 3:32 PM, Greg Mitchell <metroidphr...@gmail.com>
wrote:
> Thanks for creating this library, Michael. Your solutions for writing the
> library are creative for sure, and this library has helped with developing
> with AWS. However, I've been using the amazonica library to communicate
> with AWS components in an enterprise-scale project for about a year now,
> and I've come to believe that some of the design choices in the library and
> its maintenance are big anti-patterns. All of these are things I've
> struggled with in developing against Amazonica:
>
> * The documentation is sparse and the code is not self-documenting.
> Clojure in general tends to have worse and less documentation than Java.
> This is usually mitigated in well-designed Clojure libraries by being able
> to break into the source and read short, comprehensible functions with
> descriptive names. Amazonica is in the worst of both worlds by having no
> documentation in source, sparse documentation on github, and using
> dynamically generated code. Specific improvements to documentation I'd love
> to see: a comprehensive list of keys that credential maps and functions
> take as well as their valid values. The one or two examples per API on
> Github are insufficient for different combinations of functionality in
> real-world use cases. Pointing to AWS javadoc is not sufficient because
> Amazonica does name-munging and unwrapping - in order to understand the
> Amazonica input/output, you have to be an expert with the library and look
> at the implementation for name-munging. It is effectively a new API. A
> comprehensive list of functions would be nice, but finding them at the repl
> is a reasonable work around.
>
> * Dynamically generating an API doesn't save anyone time
> This is an extension of the previous point. You have almost 800 lines of
> code, mostly dedicated to reflection and interning methods. It's impressive
> that the whole thing works as well as it does, but doesn't actually save
> time vs. explicitly targeting an API with small wrapper functions. That has
> the benefit of being very obvious and easy to understand (as described
> above). It does mean you have to do some work when the Java SDK changes or
> you add a client, but I see there is already some nasty logic to switch on
> the client class if it has a different interface. There's a performance
> cost in reflection too.
>
> * Functions are both variadic and dispatch on argument type
> Especially without clear javadoc style documentation for function
> arguments, types, and keys, having functions that take a smorgasborg of
> different arguments is incredibly confusing. I think the root of this
> problem is the choice to make the client methods variadic, because then
> there can't be well-specified arities for the various cases (no credentials
> or arguments, credential map, just arguments, credential map and
> arguments), using repl. If the functions instead had 0, 1, and 2 arities
> that took nothing, an argument map, or a credential map and an argument
> map, it would be so much clearer. Also argument maps are generally a little
> easier to work with than destructuring the rest.
>
> * There are no releases or tags on github
> My company has a tedious process for importing third-party packages into
> source control. It's not ideal, but I'm sure it's not unique. It would be
> great to be able to pull in a stable release built against well-specified
> versions of dependencies.
>
> I hope this doesn't come across as harsh, that's not my intent. I really
> do appreciate you writing this library, and I realize that given how mature
> it is, completely changing the implementation is probably unfeasible. I
> just want to raise these concerns and see whether other people share them.
> If so, maybe they can serve as patterns or anti-patterns for future
> libraries.
>
> -Greg Mitchell
>
> On Monday, March 25, 2013 2:51:42 PM UTC-7, Michael Cohen wrote:
>>
>> Curious to hear opinions on this:
>>
>> https://github.com/mcohen01/amazonica
>>
> --
> 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.
>
--
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.
