Skip to content

Instantly share code, notes, and snippets.

@chadluo
Last active February 16, 2021 02:52
Show Gist options
  • Save chadluo/1509b44354d63cc8f6189e3c9b6280bc to your computer and use it in GitHub Desktop.
Save chadluo/1509b44354d63cc8f6189e3c9b6280bc to your computer and use it in GitHub Desktop.
On timestamp formats

On timestamp formats

Scope

Timestamp: the instant when an event happened (or will happen), be it a server log, a comment, a commit, an email, start/end of CI build, publish time/last edited time of a video/blog post etc. Should not be long lasting events.

User: the people who refer to the timestamp to find when the event happened. The event may or may not be created by the user.

This article: the string representation of the timestamp to be most useful.

Behaviour

Show everything necessary. Don't hide anything in cursor hover popup. Popups are hard to use (you'll need to manouver your cursor and precisely aim it at screen elements, given that timestamps are usually a small piece of text), slow (some popups might have set a time offset before showing up, others might need to dynamically load the content) and not straightforward (if you need to compare multiple timestamps you will have to remember all of them).

Precision

Depending on the event nature, ms for server events or other machine events, ideally seconds, or practically enough minutes for human events. You can discard the extra precision you don't need, but it's annoying when it's absent, and even worse when you cannot bring it back.

Relative vs. absolute

Use relative timestamps for recent events and absolute for further. You can be both intuitive and precise, but remember: relative time units create ambiguitiy, larger time units create larger ambiguity. You probably don't care the start/end of one clock minute; you might guess when is 'one hour ago', but 'last year', or worse, '3 years ago' will tell you nothing except it's a long time ago, and probably not so different from '5 years ago'.

24h vs. 12h

Use 24h. 12am/12pm will confuse with noon/midnight; 'am' and 'pm' takes more characters.

date month year order

Use ISO 8601.

Weekdays

If you work on a weekday based pattern, the weekdays should serve as anchors and help for recent events. Not so helpful for very old events.

Timezones

For server logs use UTC, or your team timezone if you are a local team running a local business. For other cases convert to local timezone. When you annotate timezone, don't use abbreviations.

Takeaway

if (within 1 hour before now):
    xx minutes ago
if (after today 00:00)
    today 14:30
if (after yesterday 00:00)
    yesterday 14:30
if (after this monday 00:00)
    monday 14:30
if (after last monday 00:00)
    last thursday 14:30
else
    2021-02-15 14:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment