Part 1 of 8 in the series Time in Software, Done Right
Time looks easy. DateTime.Now, new Date(), done.
And most datetime bugs don't come from bad code. They come from not understanding what we're actually talking about.
Before we write a single line of code, we need to break one fundamental misconception that causes bugs everywhere:
A date is not a moment
Let that sink in. It sounds obvious, but I promise you — this misunderstanding happens more often than you think.
Christmas Is Not a Moment
Quick question: When does Christmas happen?
You might say "December 25th". But that's not a when — that's a what. It's a day on the calendar. A label.
Think about it:
- When it's Christmas morning in Sydney, it's still Christmas Eve in New York.
- When Australians are opening presents, Americans are still wrapping them.
- There is no single global instant called "Christmas begins".
Christmas is a local date. It exists in the context of a place. Different places experience December 25th at different physical moments.
The same is true for:
- New Year's Eve
- Your birthday
- June 5th
- Any deadline written as "by [date]"
A date is not a moment. It's a calendar-day window — and that window slides across the planet.
"2 Hours After New Year" — Whose New Year?
Here's another one that trips people up.
Imagine you're building a feature:
"Show a special banner for 2 hours after New Year."
Sounds simple. But wait — whose New Year?
- New Year in Sydney happens 11 hours before New Year in London.
- New Year in New York happens 5 hours after London.
- New Year in Honolulu happens 5 hours after New York.
So when you say "2 hours after New Year", you're not describing a global moment. You're describing something that happens locally, in each user's timezone, at different physical instants around the world.
If you try to calculate this as a single UTC timestamp, you've already lost.
"On June 5th" vs "At June 5th 10:00"
Let's make this concrete:
Scenario A: "The report is due on June 5th."
Scenario B: "The meeting is at June 5th, 10:00 in Vienna."
These look similar, but they're fundamentally different:
| Scenario A | Scenario B | |
|---|---|---|
| What is it? | A date | A date + time + timezone |
| Is it a moment? | No | Yes |
| Can you convert to UTC? | No | Yes |
Scenario A is a Local Date — a calendar day without a specific instant. Scenario B is a Local DateTime + Timezone — unambiguous, convertible to UTC.
The bug happens when you treat Scenario A like Scenario B.
The Bug You Don't See Coming
When someone says "the deadline is June 5th", developers often write:
deadline = new DateTime(2026, 6, 5, 0, 0, 0) // midnight... but whose?
Midnight UTC? Midnight server time? Midnight user time? If the server is in us-east-1 and the user is in Vienna, "midnight" means completely different instants.
Here's the pattern:
- Business says: "Deadline is June 5th"
- Backend developer stores:
2026-06-05T23:59:59Z(end of day UTC) - Frontend shows: "Due: June 5th"
- User in New York submits at 11:00 PM on June 5th local time
- Server rejects: "Deadline passed" (11 PM New York = 3 AM UTC June 6th)
The user sees "June 5th", submits on June 5th, and gets rejected. The fault isn't the user's — it's the requirement. "June 5th" is not precise enough for a technical system.
This isn't an edge case — it shows up in billing, deadlines, reporting, access rules, and compliance.
What a Date Actually Is
A Local Date is:
- A day on the calendar (year, month, day)
- Without a specific time
- Without a timezone
- Not convertible to UTC on its own
Examples: Christmas, Halloween, your birthday, "deadline June 5th".
A local date becomes a moment only when you add a specific time AND a timezone. Without both, you cannot answer "has this passed yet?" with certainty.
The Rule to Remember
Anything tied to a calendar day is local. Always.
"Submit by June 5th", "2 hours after New Year", "Christmas" — all local. The only things that are truly global instants are machine events: "request received at X", "token expires in 3600 seconds", log timestamps.
What This Means for Your Code
If you're building a system that deals with dates, you need to ask yourself:
- Is this a calendar concept or a physical moment?
- If it's a calendar concept, whose calendar?
- Do I have enough information to convert this to a specific instant?
If the answer to #3 is "no", then you're working with a Local Date — and you should not pretend it's a timestamp.
In the next article, we'll look at the different types of time you'll encounter in software, and when to use each one. Spoiler: there are more than you think.
Key Takeaways
- A date like "June 5th" is a 24-hour window that slides across the globe — not a point in time
- Converting a date to UTC without a timezone is always a guess
- If users can't objectively know whether they've met a deadline, the deadline is broken — not the user
Next up: **The 7 Types of Time Every Developer Must Know* — building a shared vocabulary for talking about time in software.*
Top comments (0)