Why is January month 0 in Java Calendar?

It’s just part of the horrendous mess which is the Java date/time API. Listing what’s wrong with it would take a very long time (and I’m sure I don’t know half of the problems). Admittedly working with dates and times is tricky, but aaargh anyway.

Do yourself a favour and use Joda Time instead, or possibly JSR-310.

EDIT: As for the reasons why – as noted in other answers, it could well be due to old C APIs, or just a general feeling of starting everything from 0… except that days start with 1, of course. I doubt whether anyone outside the original implementation team could really state reasons – but again, I’d urge readers not to worry so much about why bad decisions were taken, as to look at the whole gamut of nastiness in java.util.Calendar and find something better.

One point which is in favour of using 0-based indexes is that it makes things like “arrays of names” easier:

// I "know" there are 12 months
String[] monthNames = new String[12]; // and populate...
String name = monthNames[calendar.get(Calendar.MONTH)];

Of course, this fails as soon as you get a calendar with 13 months… but at least the size specified is the number of months you expect.

This isn’t a good reason, but it’s a reason…

EDIT: As a comment sort of requests some ideas about what I think is wrong with Date/Calendar:

  • Surprising bases (1900 as the year base in Date, admittedly for deprecated constructors; 0 as the month base in both)
  • Mutability – using immutable types makes it much simpler to work with what are really effectively values
  • An insufficient set of types: it’s nice to have Date and Calendar as different things,
    but the separation of “local” vs “zoned” values is missing, as is date/time vs date vs time
  • An API which leads to ugly code with magic constants, instead of clearly named methods
  • An API which is very hard to reason about – all the business about when things are recomputed etc
  • The use of parameterless constructors to default to “now”, which leads to hard-to-test code
  • The Date.toString() implementation which always uses the system local time zone (that’s confused many Stack Overflow users before now)

Leave a Comment