Date & Time

Unix timestamps are unreadable and timezones are worse. Convert an epoch value to a real date in the zone you care about, go back the other way, and check what a stored timestamp means before you write a migration around it.

Almost every bug in this area comes from one of three things: a value in milliseconds compared against one in seconds, a date string stored with no offset so nobody can later say which zone it meant, or a daylight-saving transition that made a scheduled time either not exist or happen twice. A timestamp is the right thing to store precisely because it carries no timezone — it is a single instant, and the zone is a display choice.

Durations are the other half of the problem, and they arrive in as many shapes as dates do: 2h30m from a config file, PT2H30M from an API, a bare number of seconds from a log. Converting between those, and totalling a column of them, is its own job.

The everyday version is clock arithmetic: adding up hours and minutes that will not add like ordinary numbers, working out what time it will be seven and a half hours after a 9:30 PM start, or totalling a week’s timesheet — breaks off, night shifts across midnight, overtime past 40 hours or 8 a day, and the pay it comes to.

Repeating events are harder still. An iCalendar RRULE packs a whole recurrence into one line, and the difference between the third Thursday and every third Thursday is a single token nobody reads correctly at a glance. Seeing the dates a rule actually produces settles it.

For the wall or a planner, a calendar prints too: a month to a page with room to write and lines for notes, every month of a year as one PDF, or the whole year on a sheet — Monday or Sunday first, A4 or Letter, with ISO week numbers if you want them.

And the week itself has an answer here: the ISO week of any date, the Monday and Sunday of any week, the dates of a quarter and of a fiscal quarter starting in April, July or October, and every week of a year listed, including the 53rd that some years have.