Basics of working with date and time for Software Engineers, Developers and Programmers

Mastering Time in Software

Time is one of the trickiest concepts in software development. Well, it is not. I am just baffled by how many things with software around me get it wrong from IoT devices to big vendor SaaS solutions. If you don’t handle it correctly, things can break in surprising ways. This post will give you a solid understanding of how to think about and work with time in software.

We’ll cover four key topics:

1. Time Offsets – Why you should always attach offsets to your date-time values.
2. Time Zones & Daylight Savings – Why time zones are not the same as time offsets.
3. Unix Timestamps – The binary representation of time.
4. ISO 8601 Timestamps – The text format for working with time.

I assume you already know how a calendar and a clock work—otherwise, this would be a kids' video, not one for programmers.

---

1. Time Offsets

A time offset is the number of hours added or subtracted from Coordinated Universal Time (UTC) to get local time.

Take a look at this UTC offset map. Each vertical line represents a time offset boundary. The UK, located around 0° longitude, uses UTC+0, also known as Greenwich Mean Time (GMT) or Zulu Time (Z). Other regions shift their time forward or backward relative to UTC.

Example:

• Sydney, Australia, is UTC+10. So if the sun rises at 6 AM UTC in Greenwich, it also rises at 6 AM local time in Sydney—but 10 hours earlier in UTC.
• Some islands in the Pacific use UTC-11, meaning Sydney gets their sunrise nearly a full day before them.

This is why storing local time without an offset is dangerous. If someone in another time zone reads that data, they won’t know what it means without an offset reference.

Best Practices:

• Always store time offsets when saving date-time values.
• Or, even better, store everything in UTC and only convert to local time when displaying it.

---

2. Time Zones vs. Time Offsets

A time zone is a geographical region that follows a set of time rules, including daylight savings time (DST). A time offset is just a fixed numerical adjustment (e.g., UTC+10). These are not the same thing.

If software asks for a time offset (e.g., "Enter your offset: GMT+10") without mentioning a location, I know it’s going to be wrong for half the year.

Example:

• I live in Australia/Sydney.
• For half the year, we use AEST (UTC+10).
• The other half, we use AEDT (UTC+11) due to daylight savings.

Without tracking both the time zone and the offset, your software may display incorrect times when daylight savings kicks in.

Best Practices:

• Use time zone identifiers (e.g., "Australia/Sydney") instead of just offsets ("+10:00").
• If using system time, most modern OSes handle daylight savings for you.
• If working with embedded systems (e.g., drones, microwaves), you may need to manually account for DST changes.

---

3. Unix Timestamps

Unix timestamps are the most common way to store date-time values in software.

A Unix timestamp represents the number of seconds since January 1, 1970, 00:00:00 UTC.

Key Features:

• Always in UTC (no offsets needed).
• A simple integer, making it fast and efficient for storage and calculations.
• Most databases store date-time values as timestamps under the hood.

Common Variations:

• Standard Unix timestamp: Number of seconds since epoch.
• JavaScript timestamp: Number of milliseconds since epoch (Unix timestamp × 1000).

The Y2K38 Problem

• Unix timestamps are typically stored as 32-bit integers.
• They will overflow on January 19, 2038.
• The solution? Upgrade to 64-bit timestamps (which will last billions of years).

---

4. ISO 8601 – The Best Text Format for Time

If you need to store or transmit date-time as text, use ISO 8601.

Example:
2023-11-28T21:34:57.123Z

• YYYY-MM-DD (Date)
• T (Time separator)
• HH:MM:SS.sss (24-hour format with optional milliseconds)
• Z (Zulu time, i.e., UTC)

Why ISO 8601?

• Unambiguous: No confusion between 01/02/03 (is that DD/MM/YY, MM/DD/YY, or YY/MM/DD?).
• Sorts correctly: Alphabetical sorting works as chronological sorting.
• Widely supported: Most programming languages and databases support it.

If you must store local time, always include the time offset:

• 2023-06-28T21:34:57.123+10:00 (Sydney during standard time)
• 2023-11-28T21:34:57.123+11:00 (Sydney during daylight savings)

---

Final Thoughts

Time handling in software is tricky, but here are the golden rules:
✅ Store UTC timestamps whenever possible.
✅ If using local time, always include a time offset.
✅ Prefer ISO 8601 for text representation.
✅ Use time zones ("Continent/City") instead of just offsets ("+10:00").
✅ If using Unix timestamps, ensure your system supports 64-bit timestamps before 2038.

Get these right, and you’ll avoid painful time-related bugs. 🚀