Dates, Done Right
Reviewing the bidding, Tinderbox’s date conversion routines sometimes were sometimes off by one day when entering dates in the 19th century and earlier. The precise date before which the error is observed varies for different customers, from a date in the 1840s to one in the 1880s. The error is completely consistent when you observe it, but doesn’t affect everyone all the time.
What on earth could explain this?
The Answer. Tinderbox dates are points in time. When you say, "July 4, 1776," Tinderbox needs to choose some specific moment on that date. Some programs choose an arbitrary time -- noon, say. Tinderbox chooses whatever the current time is.
But there was one thing they had forgotten. The current time depends, of course, on your time zone. Internally, dates are stored in Universal Time, but you don’t care about that. So, we do a simple two-step:
- Get the local time, 10:24 today
- Convert it to Universal Time. So that’s 15:24 today.
- Convert July 4, 1776 to Universal Time.
- Set the clock to the current time. Now it’s 15:24 on July 14, 1776.
- Convert back to your local time
But, back before they invented railroads, there were no time zones. And OS X knows this! So, before time zones were introduced, the local time doesn’t get shifted to the time zone. And, if your local time is one a different calendar date than Greenwich, you’re off by one day!
Once you see this, it’s easy to fix. When you’re looking at a page full of CFDateRefs, it’s harder to see.
Lessons:
- Tinderbox date arithmetics is fairly well tested, yet this got through it all. No one is going to anticipate bugs like this, bugs that depend on the invention of the railroad. TDD is great, but Coplien is right; you’re never going to get everything through testing.
- Apple’s documentation policy attempts to tell you what you need to know, and no more. This gives Apple flexibility to improve OS X in small ways without breaking its implicit contract with developers, and keeps the documentation small. Here, though, the time zone behavior is completely undocumented. There’s a table somewhere what says "Eastern standard time begins in 1840, but Japan Standard Time begins in 1888,” but if that’s documented anywhere, I don’t know where, and neither do you.
- A surprising number of historians use Tinderbox.
It wasn’t that long ago that you couldn’t enter a date before 1904 on a Macintosh.
Update: And here are the rules for Time Zones, thanks to Tom Harrington.