Hi Greg, I think all of your criticisms are very valid, and I think I've seen most of them voiced by others at various times. I wrote it in about 3 weeks in March of 2013, when I was very new to Clojure, so I'm sure I made lots of mistakes. I was using some Java with AWS and some Clojure, with James Weaver's rotary library, and when you look at the Javadocs, it almost seems like the Java SDK could be generated. So that leads one to think....and off I went.
As far as the problem areas you identified: - shitty docs What can I say, guilty as charged. Sorry. I tried to do a decent job with the examples, although I laughed when I heard Stu Halloway slag off "documentation by example" in some tech talk. Oops. What else could I do? I looked at trying to generate some more codox type docs from the Java SDK, but I just wasn't going to endure that pain. So, yeah, I hear you. It's a trade off though. I'm sure there's a few folks out there that would have to use Java interop and the Java SDK (and pour through those same Javadocs) in order to use one of the less popular AWS services if Amazonica didn't exist, because nothing else would exist in the Clojure world for that particular AWS service. Man, when I wrote this I don't even think there was a decent Clojure lib for ec2. - dynamically generated api Yeah, the code is not as straightforward and reflection is expensive. The counterpoint to that I guess would be, once you have it well sorted, you don't really need to edit core.clj too much. And with most of the AWS api, the cost of reflection is negligible compared to the network hop. You're also probably not that concerned with latency at all for those use cases. But again, it's a trade off. Buy one get 20 was worth a little reflection to me. - Functions are both variadic and dispatch on argument type Again, guilty as charged. I would do things differently today. - There are no releases or tags on github Again, I didn't really know what I was doing here, and never really changed the approach. What do people expect, a snapshot release for current development, and periodic version bumps and releases (less frequently than Amazonica currently bumps the version numer)? Mike On 11/20/14, 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 a topic in the > Google Groups "Clojure" group. > To unsubscribe from this topic, visit > https://groups.google.com/d/topic/clojure/QcGi4lPYi1s/unsubscribe. > To unsubscribe from this group and all its topics, 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.
