Date Formats
2025-0418 Auckland, New Zealand.
Working with time generally sucks, this is known. But over the years I've slowly built up rules of thumb for designing systems that work with time. I've also developed a format that I find a nice middle-ground for being both machine- and human-readable.
On representation: prefer built-ins (if they're good)
Go's time.Time package
Python's datetime package is alright; though you have to have certain arcane patterns memorised to get good results (e.g. datetime.now(timezone.utc) until very recent versions of Python.
On designing representations
99% of the time I'd suggest using some integer number of milliseconds or microseconds since some epoch.
Pick a precision and scale as necessary; I'd generally lean towards finer grain.
A uint64 number of nanoseconds can cover up to 581 years.
On timezones
Again the usual advice is a good starting point: use UTC internally everywhere, only convert to user-local timezone for display purposes.
It's a good starting point but it doesn't cover every situation. Make sure to talk to your stakeholders and figure out what they actually need! (Which is not always what they say they need). When they say "daily" do they mean "every day at 9AM?" or "every 24 hours" (these are not the same!)
By the way: timezones change. Often. Yes, often enough that you cannot ignore it in your application. You can probablyrely on the system's tzdata being up-to-date (but again, depends on your application).
On reading & writing dates (by hand)
Most people probably write the date something like this: 12/03 which hopefully we can all agree is plain awful (is it 12th of March or 3rd of December?).
12/03/26 is marginally better by includng the year, I suppose.
Being a programmer thrice-burned nine-times-shy I used to use 2026-03-12.
Nice, unambiguous, though sometimes gets you a weird look from normies.
Something I don't like about it is the imbalance between the four digits on the left and the two packs of two on the right.
When you're looking at a bunch of dates it can sort of all turn into a big mush of numbers.
Instead, I like to use 2026-0312.
Two fours, nicely balanced.
Marginally easier for my eye to parse as two numbers rather than three.
It also splits across lines into a nicely aligned format:
2026
0312
Extending to include hours+minutes is rather natural, too:
2026
0312
1452
but I don't find myself using that (or the one-line 2026-0312-1452) very often.
Again, things tend to turn into a big mush of numbers when you're looking at a bunch of them.
Obligatory XKCD.
On events that humans will be attending at a physical place
Things get a lot more complicated. 1) You probably need to use the local timezone of the place where the event is taking place, which is not necessarily the same as the user's client. 2) You'll probably have to store both the UTC instant when the event is supposed to happen as well as that local timestamp. I remember reading a really good blog post about this but I forget where it was.
On timestamps for file names that humans are expected to read
My natural instinct used to be to simply use some high-precision ISO 8601-style format like 2026-03-12T14:52:04.942Z in the file name.
It has all the usual benefits of 8601 timestamps after all: unambiguous, precise, sortable, and a person can read it and make sense of it.
Takes some effort though: there's a lot of --T::.Z noise to sort through when reading it.
It's an extremely dense format.
Instead I've taken to simply using a sequence ID: 2026-0312-000, 2026-0312-001, 2026-0313-000 and so on.
Still unambiguous and precise (not about the time but about the ordering of the documents), sortable, and much easier to read.
It's also just better-aligned to how humans work, I think.
"Oh, that was the first one I ran yesterday" or "the third one I made today" is more natural to talk about than "the document for 17774920374".
If you need the precise timestamp I'd recommend just containing it within the file content.