Rename Temporal.Absolute to Temporal.Instant

[littledan]

The name Temporal.Timestamp has been floated, and after sitting on it for a bit, I think it's more intuitive than Temporal.Absolute (or the previous name, Temporal.Instant). I don't want to go in circles forever, but I'm wondering if folks would be open to some more bikeshedding here... :)

[ljharb]

I agree, Timestamp is the best name of the three.

[mikemccaughan]

Timestamp is intuitive if you've worked with systems that use that name for the idea of a fixed point in time, but not so intuitive if you haven't... The word is never used in the ECMAScript standard. But maybe that's a good thing if you're looking to distinguish this proposal from Date.

Anyway, thought I throw an outsider's perspective into the mix.

[ljharb]

Considering that covers, to start, "any unixy shell" and "any database system", i'd be surprised to hear there's folks that find it unintuitive. (but i hope to hear from them so their voice is represented!)

[littledan]

@mikemccaughan What do you think of the names Temporal.Instant and Temporal.Absolute?

[mikemccaughan]

Well, I've worked in the software development space for 20+ years, and never really understood the word timestamp. I've certainly seen it used occasionally in database schema, but almost exclusively as a utility column for concurrency checks. Never as a column from which to derive meaningful data. Those were always date or datetime. Likewise dallying with *nix and Linux (e.g., getting a website spun up, working with git from bash, or doing quick work on an AIX system), I don't think the command line ever demanded that I understand that I know what the word timestamp meant. I'm sure I saw them, but I always interpreted them as dates and times.

In any case, once I read what Temporal.Absolute meant, it made sense to me, as someone who's done quite a lot of work with the Date object in JS, DateTime and its ilk in .NET, etc.

Temporal.Instant would also work, but I feel like the word's other forms (adjective, adverb) would cloud the issue. The problem of colloquial usage comes into play here too. "Come here this instant!" generally doesn't carry a lot of date information with it -- it's pretty much now or at least within a few seconds. Same with advertising; "Instant Ramen" is not ramen you're going to have to wait more than a couple minutes for.

I think Timestamp might work fine too, but the fact that it has the word "time" in it, but not "date" might throw some people off. Like, "I'd use Temporal.Timestamp but I need the date too". I don't know if you all spend much time on Stack Overflow, but if you do, and spent much time following the [javascript] tag, you'd probably find my expectations of developers' knowledge to be actually quite high :).

Thanks for taking input from those of us who will be using these constructs. I'm really excited to see this proposal succeed!

[justingrant]

A week ago I would have agreed to switch to Timestamp, but I changed my mind after writing TypeScript types and some sample code. Here's why: having this class name be an adjective made it easier to name and describe other things. For example:

• JSDoc comments that described DST-safe time arithmetic as "absolute math" or "absolute time calculations"
• A utility function that accepted an options: {calculation: 'absolute' | 'local'} parameter
• A duration that came from Absolute.prototype.minus was named absoluteDuration

The problem with "Timestamp" (or other nouns like Instant) was that it was hard to apply to other things (calculation modes, durations, functions) that relate to timestamps but weren't actually instances of Timestamp. In other words, there's both a Temporal type and an underlying concept that applies to things like durations that are not instances of that class. A good name would support both.

On the other hand, a noun like "Timestamp" probably enables clearer naming of things that are timestamps, e.g. birthdayTimestamp vs. birthdayAbsolute or absoluteBirthday.

My guess is that the second problem is less bad because once users actually use the API, they'll recognize the class name in variable or function names, even if those names are ungrammatical. But if users can't understand the concept of "absolute time" or connect it with the Temporal class name, then developers will never be successful in using the API.

So I'd suggest to keep it Absolute, or to pick another adjective-friendly term what would work for "Xxx Duration" or "Xxx Time" or "Xxx Date" or "Xxx Calculation" or other related concepts.

BTW, one thing that occurred to me is that the name DateTime also doesn't match what its underlying concept is called (e.g. "wall clock time") in docs or GH issues. This might be one reason why its concept has been challenging to explain to noobs. I don't have a good answer other than finding some prefix, e.g. "ZonelessDateTime" or "PlainDateTime" that could be used to name the concept.

[littledan]

Thanks for these thoughts. I can see how the juxtaposition of "Time" and "Timestamp" is rather confusing. I guess my current preference is to stick with the name Temporal.Absolute.

[ryzokuken]

Just to chime in here, I'd also comment here to record my preference for Absolute. It's not a term people are very familiar with, but it's one that they get a decent understanding of very quickly, while something like Timestamp assumes prior programming experience.

[ljharb]

"timestamp" isn't solely a programming term; that's also the term for the date/time overlay on a great many home videos (pre-smartphone), and on every security camera footage shown on the news or on Cops. I'd say it's a relatively commonly understood term in the US to mean "date and time" among non-programmers.

[sffc]

Timestamp is the word used pretty much everywhere else, especially in databases. You have to learn it sooner or later. Some programmers will come to JavaScript already knowing what a timestamp is, and others will learn it for the first time by using JavaScript.

The benefit of building off some programmers' previous mental model of timestamps from databases is a big advantage. It makes it more clear what the difference is between a Timestamp and a DateTime.

Instant is the word used by java.time. I haven't seen Absolute used anywhere else.

I would rather we don't invent new words and just stick with the industry terminology. So my vote is for Temporal.Timestamp.

[justingrant]

I agree with @sffc that Timestamp and Instant seem like the best options. I don't have a strong preference for either of them over the other.

I've changed my mind from my May 23 comment above because the main reason I previously preferred Absolute was because it was useful as an adjective or the name of an option string. This justification is now irrelevant because because we decided to remove all the features from LocalDateTime (e.g. duration kind options) that required this adjective or option.

[ptomato]

I have preferred Timestamp since it was first mentioned. As pointed out it might not be obvious if you've never heard that term before, but I think it's more obvious than Absolute or Instant.

We've also gotten some amount of feedback that it's not obvious how to get a timestamp or that people don't understand how the name Absolute describes what the type does. I think renaming to Timestamp would help with both, particularly Temporal.now.timestamp() would help with the former.

[sffc]

I think the key issue is education. Using Timestamp or Instant helps programmers bootstrap into Temporal, and saves our valuable education budget for subjects like calendars and time zones.

I subjectively think Timestamp carries broader educational value. It is common in database terminology, and @justingrant pointed out that a Google search for "timestamp" pulls up more relevant results than a search for "instant". However, programmers coming from Java are already familiar with Instant, which may carry more weight than I've previously put on it.

[justingrant]

I think the key issue is education. Using Timestamp or Instant helps programmers bootstrap into Temporal, and saves our valuable education budget for subjects like calendars and time zones.

IMHO, #884 is an example that supports @sffc's point. In that issue, the developer didn't understand what "Absolute" meant, which made it hard for him to understand what DateTime was used for, which in turn made it hard for him to do the most basic use cases with Temporal.

Keep in mind that this is a developer who was conscientious and read the docs and still was confused. If this conscientious developer was confused, the median developer would probably have an even harder time.

Having a name that's more recognizable probably would have reduced this confusion and let the developer boot up his knowledge of Temporal more easily.

[sffc]

Please retweet: https://twitter.com/_sffc/status/1304258685263380480

[jasonwilliams]

Some thoughts

Timestamp doesn't sound right to me for 2 reasons.

1. Absolute is an object that you can get a timestamp from but it's not a timestamp in
   of itself. For me Timestamp usually refers to the outputted data (the actual string, hence stamp), where as this is far more than that.

In some places you can generate a timestamp, which would be like the toString() equivalent here.

2. In databases (where a majority of users may have heard the term) TIMESTAMPs don't always have to be zoned, they can just be a date and time.

I think if we're going for the education angle here timestamp is the worst choice, because there's already enough documentation out there that shows it doesn't have to be an absolute point in time[1], whereas in our case it is.
You don't have this problem so much with Absolute or Instant.

If we're confident Timestamp for the majority (whether educating themselves with other resources or not) means UTC Timestamp and not just any timestamp then fair enough, but i'm not sure about that.

I didn't mind Absolute as it represents an absolute point in time (and I think this is easier to educate). But if I have to pick between Timestamp or Instant then Instant is preferred.

[1] - https://www.postgresql.org/docs/9.1/datatype-datetime.html
[1] - https://en.wikipedia.org/wiki/Timestamp

[ryzokuken]

I think the result of the poll also preferred Instant. Does anyone here have strong objections against Instant?

[ptomato]

In the Sept. 17 meeting we decided on Temporal.Instant.

[ljharb]

I still prefer Timestamp, and that was pretty close to Instant in the poll. What are the arguments to prefer Instant over Timestamp?

[ptomato]

I also still prefer Timestamp personally, but the main reason to prefer Instant was the familiarity with the name from other places such as Java (#602 (comment)) and Jason summarized some other ones (#602 (comment)).

[sffc]

I still prefer Timestamp, and that was pretty close to Instant in the poll. What are the arguments to prefer Instant over Timestamp?

Most of the reasoning is expressed above in this thread. It boils down to the fact that although Timestamp has a lot of advantages, it has a number of problems that @jasonwilliams and @pipobscure have pointed out. Instant is a compromise that has most of the advantages of Timestamp.

[ljharb]

I don't find "it's easier for Java programmers" a compelling motivation to pick anything.

#602 (comment) is compelling though; I don't see any comments from @pipobscure in this thread.

[ptomato]

"other places such as Java" not "exclusively Java"

[pipobscure]

Timestamp has a specific meaning in computing. Naming this type such suggests that this is the main characteristic of it. But reality is that Timestamp is a tiny subset of the semantic meaning of this type. As such naming it Timestamp would be extremely misleading.

Which is why Absolute is my preference, since it doesn’t have that baggage which allows for the important concepts to be imparted to it by us.

However I will go along with naming it Instant because it is at least less predetermining and what it suggests is much broader as well as much closer to what the type actually is.

[sffc]

Instant is the prior art in at least Java, C#, and ISO-8601. By adopting that convention, we help unify the developer ecosystem around one term, which not only helps Java/C# developers coming to JavaScript, but will ultimately help JavaScript developers going to those other languages. It seems like a win-win.

[justingrant]

My main suggestion before deciding on the name would be for everyone to read #884 if you haven't read it already. It's an example of a brand-new-to-Temporal developer trying to figure out what Absolute is used for, and it was a good reminder that naming might have been able to help.

My question is: would either Instant or Timestamp have better helped this developer figure out the role of the type currently known as Absolute?

My (weak) preference is still for Timestamp over Instant (because there are more JS developers who use relational databases than use Java), but I think both are much better than Absolute.

[ljharb]

I certainly agree that either name is better than Absolute :-)

[stebogit]

As @pipobscure and @jasonwilliams suggested, a timestamp has a specific meaning in programming:

a sequence of characters or encoded information identifying when a certain event occurred

which is in fact what the toString method returns.

[ptomato]

This is done now.