Nahid Akbar

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:

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:

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:

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

Best Practices:

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:

Common Variations:

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

Why ISO 8601?

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

Final Thoughts

Time handling in software is tricky, but here are the golden rules:

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

Written December 2023
© Nahid Akbar