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 and/or if your business is global.

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

Note: Timestamps are also known as instants or incremental time.

Note: Do not mix up a local datetime value (2019-01-23 01:23:45) with a timestamp value (2019-01-23 01:23:45 UTC). A local datetime is something completely different.

Note: A zoned datetime may also be used as a timestamp, but I will argue that it should be avoided.

Note: If you need to examine different timestamps, the Timestamp magician may be of help.

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.

Note: UTC is also known as Zulu time.

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. If you are stubborn, you may have to take a few more walks around the block.
4. Okay, if you are sane, but still want to throw yourself, your product and your company 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 (1) 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, since you undoubtedly will fail sometimes. So I emphasize that the time zone part in the timestamp, should always be UTC (indicated by the "Z" (Zulu) in the example above).

Note: An excellent blog post about why you should not parse localized strings and never use localized strings as interchange format.

Formats for displaying timestamps

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. You have no idea who (or what) will read those timestamps.

Note: An example of how you can help your audience and display timestamps in a structured way.

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-30T18:30:45Z.

Note: I blame programming languages like JavaScript and Java for some of 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.

Also remember, one of the most important objectives when you are some kind of author, is to make it easy for your audience to understand what you have written.

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.

Note: Below, you have the UTC time displayed with the NNM Clock.