Or why machine-human win-wins are important.

Today we’ll be looking at different approaches for solving one of the age-old problems in programming: how to best represent time?

First, let’s get our definitions right.

A Date represents a specific moment in time, whether in the future or the past. Hence, its representation must be relative to some other known, specific moment in time — think of it as an “anchor” date.

A Period represents an interval of time, between any two moments in time. Hence, its representation is absolute and independent from whichever moments it’s bound to.

Dates

Take as an example the 3rd of July, 1997. Its “anchor” isn’t the month of July, or its 3rd day, nor even the year 1997. In simple terms, its anchor is actually the year zero, from which we count 1997 years, 7 months, and 3 days.

Of course, we rarely think of this usage of the year zero when naming modern-day dates. Why would we? After all, none of us were around the year zero. In fact, every individual tends to have their own personal anchor date from which they can relate to a specific past or future date—like their date of birth. Today, a person born in 1945 will relate to the year 1968 as “the time when my life was starting”, whereas a person born in 1997 won’t even regard 1968 as a year to relate to at all.

And so, when speaking in programming terms, dates can be represented with a variety of anchors too.

In its simplest form, we can represent a date as an amount of seconds between an anchor date and our date. So, to represent the 3rd of July, 1997 at 17:30, choosing the 1st of January, 1970 at 00:00 as our anchor date, we calculate the amount of seconds in between the two dates and arrive to 867,951,000 seconds as a result.

Though it could have been, our choice of anchor date in the example above isn’t random. Originating from UNIX systems, that date is regarded as the epoch date from which every other date can be represented. The year 1970 was chosen because UNIX was born around that time. Thanks to this standard, the anchor date becomes implicit and systems only need to rely on one value to transfer and interpret a date like the 3rd of July, 1997 at 17:30—867,951,000.

However, while it’s well known that machines have an easy time with numbers, humans on the other hand struggle to understand what 867,951,000 seconds from 1970 even approximates to. And more often than not, building good software entails understanding, tweaking, and experimenting with the raw values the program deals with. So while our first approach is a win for machines, it’s not so much so for developers.

Alright, so how about representing the date in writing? “03/07/1997 17:30” is easy enough for a machine to understand, right? There; machine happy, developer happy.

Well… not quite. Without context, an English developer will understand it as the 3rd of July, and an American developer will understand it as the 7th of March, and so their different understandings will shape different code that will act erratically depending on where you’re from.

Most bugs aren’t from lack of skill, but from excess in assumption. So we need a format to understand and represent dates universally without cultural misunderstandings or biases.

And that’s where the ISO standard comes into play.

The International Organization for Standardization has a standard for date representation that’s broadly used in software: ISO 8601. The 3rd of July, 1997 at 17:30 represented through ISO 8601 reads as follows:

1997-07-03T17:30:00Z

Not a plain English description, but pretty close. It’s a recognizable, consistent format, and the order of components is very easy to remember: from biggest to smallest; year, month, day, hour, minute, second.

I won’t go into details about the specification or usage in code, since every platform exposes this standard in a different way. The most important thing to know is that inputs and outputs are always consistent if the standard is correctly implemented.

Machines win, humans win.

Periods

How would you represent 1 hour?
Well, we can just use the number 1. Done!

So how about representing 3 minutes?
Same, we just use the number 3. Easy!

Right… and how about 1 minute?
Well duh! Just use 1 agai-… oh wait, this 1 and the previous 1 don’t mean the same thing… okay how about doing everything in seconds?

So 1 minute would be represented as 60 seconds?
Sure!

And 1 hour would be represented as 3600 seconds?
You got it!

How about 1 day?
Well, one day is 24 hours… so 24 times 3600… 86400!

Cool. Now tell me, how many months are 13,150,000 seconds?
Oh boy.

When it comes to intervals of time, programmers tend to approach the issue with a purely numeric mentality. Lengths of time can easily be represented by a single number, so why not just agree on a unit and do just that?

Again, it comes down to which side wins. Machines are delighted to operate with big numbers, however humans struggle to even conceive of 13,150,000 consecutive seconds, much less interpret that amount as “around 5 months”. Again, building good software entails understanding, tweaking, and experimenting with the raw values the program is dealing with. Again, the approach is a win for machines, and not so much so for developers.

Thankfully, ISO 8601 comes to the rescue again on this one. Part of the specification includes a way to represent periods of time. And it looks like this:

P3Y6M4DT12H30M5S

Whilst initially it may look like I hit the keyboard with my forehead with caps lock on, the above is surprisingly easy to understand once you learn what each letter means:

> P3Y6M4DT12H30M5S
> P 3Y 6M 4D T 12H 30M 5S
> P 3Years 6Months 4Days T 12Hours 30Minutes 5Seconds
> Period (of) 3Years 6Months 4Days Time 12Hours 30Minutes 5Seconds

Better, isn’t it? Notice also how this format’s order and notation mirror that of ISO dates, from biggest to smallest: year, month, day, hour, minute, second.

What if we just need to represent 3 days? Easy, we drop every other component and get to:

P3D

How about 3 days and 2 minutes?

P3DT2M

And just 2 minutes?

PT2M

Note: P is always mandatory, whether we have days, months, years or not. T must be present if specifying hours, minutes, seconds (to disambiguate between months and minutes).

Machines win, humans win.