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.
