I just wanted to say that while amazonica is also my AWS library of choice, and I'm so glad it exists, and "running code wins", I also run into all the same issues that Greg listed.
On Thu, Nov 20, 2014 at 12: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.
