Favicon NNM Sandia Mountains from Kiwanis cabin (New Mexico, United States), April 2009 (Photo: Anders Gustafson) Favicon NNM
Modified 2021-04-20T16:38:29Z

If you, as a system developer or product owner, have to handle timestamps in your system, you have to think about a few things. Especially if you plan to show your users these timestamp values.

Note: A timestamp denotes a unique, unambiguous point on the timeline, i.e. an exact moment in time.

UTC is your friend

As long as we use our current timekeeping system with the utterly complicated time zone rules, the Coordinated Universal Time (UTC) will probably be your best choice.

  1. If you decide to not use UTC everywhere, think again.
  2. If you still want to use other time zones than UTC, please, take a walk around the block, and then reconsider your decision, by reading about pros and cons with time zones.
  3. Okay, if you are sane, but still want to throw yourself into the time zone mud, you can at least consider the following:
    • Are you going to store all your timestamps in UTC, otherwise think again. (With all I mean exactly all, not most, not some, not the majority.)
    • Are you going to show your users any of your timestamps without explicit time zone information, think again. Or better yet, never do this.
    • When using different time zones, please skip the useless abbreviations (eg CET, EST, IST). Also avoid to only use identifiers (eg Europe/Stockholm, America/Los_Angeles), since they lack actual offset information. Make sure to always include correct offset information.

Formats for clients

Only allow one format for sending and receiving timestamps. Never implement APIs that allow several different formats for defining timestamps, where you are responsible to parse and convert these timestamp formats correctly. If a client wants to use obscure timestamp formats in their own special locales, that should be the burden of the client, not the burden of your system.

The best format out there at the moment is the ISO 8601 extended format (for example 2019-01-23T01:23:45.789Z), so there are no reasons or mitigating circumstances to ever use anything else.

Note: By obscure timestamp formats above, I mean formats not following ISO 8601, but also formats with other time zone offsets than "Z".

Note: You can not be a winner if you decide to support different time zones. So I emphasize that the time zone part in the timestamp, should always be UTC (indicated by the "Z" in the example above).

Displaying formats

With the same arguments as above about the burden of your system, I really recommend to only use the ISO 8601 format for displaying timestamps.

Be explicit about the timestamp value. Make sure the timestamp value is understandable by everyone around the globe.

Supported languages

A note about the maintenance nightmare you will encounter if supporting several languages. I really recommend to only use English as language. Otherwise you will have a hard time keeping all your translations up-to-date and with quality, especially if you are supporting languages that you are not fluent in.

If you, against your better judgment, decide to support several languages and formats, never ever mix language and format together. Always make sure that a user can configure language and format independently. Many of your users may want to use English, but still use the understandable ISO 8601 format.

Settings configured by user

If you are using different time zones, you also have to keep in mind that a user can configure her preferences in many places. You may have a time zone configuration option in your application, but the computer system may also have such an option. These settings may not be the same and which of the settings that is used is not always trivial to understand, neither for you nor for the user.

Note: You can read more details about this in the Computer systems section of Time zones - to be or not to be?.

Naming conventions

Avoid naming variables like dateCreated, dateUpdated, etc and then storing timestamps in these. There is quite a difference between a date and a timestamp. You will always confuse people if you in a variable named dateCreated store values like 2020-11-30T08:00:00Z.

Note: I blame programming languages like JavaScript and Java for these problems, since they for a long time have had classes named Date that actually correspond to timestamps.

Conclusions

As always, keep it simple. It is difficult to be agile, when walking around in mud up to your neck.

If you use UTC and one common format everywhere your life will be a walk-in-the-park and your users, all around the world, will unambiguously understand the timestamp values they are seeing. The other paths may be dark and cumbersome and you have been warned.

First published by Anders Gustafson 2018-09-01
Logo for NNM
NNM Logo
Friends in need
CCF Cheetah Conservation Fund
NNM Clock
Random quote
The best code you can write is code that accomplishes something complex, but is inherently understood by those who examine your codebase.
Laurie Barth