[Pojomatic-users] Pojomatic API decisions

[Chris H. <han...@gm...>]

I was (re)watching Bloch on API design the other day (
http://www.infoq.com/presentations/effective-api-design ) and I had a couple
of takeaways which apply to Pojomatic. We need to discuss/address these
before it's too late, meaning before 1.0.

1) Provide programmatic access to all data available in string form.  Among
other things, this prevents users from parsing the string output.
1a) We can, and I think should, refactor the Differences API for
programmatic access. We could take a page out of the Google Collections book
on this one:
http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapDifference.html

I will work on this one.

2) Design for extensibility. If you have a successful API, the users will
want to do more with it. Even if you get the API right the first time, you
won't get it complete the first time.
2a) One way to do this would be to implement extension separately from the
existing hashCode(), equals(Object), and toString() functionality. That
would be a small API change which could be done as a point release after
1.0, but then existing functionality would be inconsistent with the
extensible API and might even become a candidate for deprecation at that
point.
2b) Another way to go would be to create the extensible API and refactor the
existing functionality to use that API right away. This is worse in the
short term because it delays 1.0, but might pay off in the long term.

To me, the question is not if we should create an extensible API, but when.
What do you think?

Thanks,
-Chris