[alblue]

The original Java date and time API was probably one of the worst APIs ever invented, as I describe in my answer on StackOverflow: http://stackoverflow.com/a/1969651

However the new javax.time APIs (created by Stephen Colebourne) are excellent and probably one of the best designed APIs. It's funny what twenty years difference can make :)

[jcranmer]

It's worth noting that much of the original java.util.Date class was based on the same misfeatures as POSIX C:

1. Leap seconds? Those don't exist, right? 2. Years date from 1900. 3. January is Month 0 (ignoring the fact that there is already a widespread convention of numbering January 1).

Of course, the "fix" of Calendar didn't attempt to fix any of the POSIX-did-it-first problems but instead mostly limited itself to supporting other locales by allowing non-Gregorian calendars.

[stygiansonic]

Totally concur. But date/time is a hard thing to get right!

However, getting it wrong the first time is different than getting wrong again, as you pointed out with the Calendar type. 0 == JANUARY, but most other things are indexed from 1...

Third time's the charm, I guess :) Getting the input from Stephen Colebourne (of Joda-Time fame) was undoubtedly a key point in getting this done.

[jandrese]

Numbering months from 0 is obnoxiously common in these time APIs. This is one of the few edge cases where IMHO we should index from 1, because people frequently just use the numeric version for output and it is way too easy to forget to add or subtract 1 from the month value. The memory lost by having an empty 0 spot in the month name array is absolutely not a concern in any sane project.