"civil" or "local" or "plain" or "naive" or something else?

[BurntSushi]

One of the more challenging naming decisions in Jiff is what to call inexact time. The main problem is that there isn't actually one clear industry standard term. This means that there isn't one obvious choice to make, even if I happen to dislike it. With that said, there are, IMO, four plausible choices for the naming of inexact time.

Firstly, and the closest thing to an industry standard term, is "local." Notably, java.time and .NET's Noda Time both use LocalDateTime as the name of the type for inexact time. IMO, there are two things working against "local" as a name here:

1. Firstly, like the other choices, it is not ubiquitous. Temporal, for example, chose not to use the "local" terminology. If Temporal had chosen "local" to describe inexact time, I think that would have pushed me over the edge and I would have used it too.
2. "local" is used to describe other distinct things that are very closely related. For example, the "local" time zone. And we see it used on Unix as /etc/localtime. That is, the word "local" is describing the set of rules used to map an absolute time to a date and time that you see on your calendar and clock. Moreover, I personally (before I started working on Jiff) was deeply confused about what "local" time even meant. It always seemed to be used in slightly different but similar ways, and it made it difficult for me to grok it. In other words, with my "beginner eyes" on, I see "local" as a confusing term. If it were more ubiquitous, I think I would have ultimately favored going with the crowd over something else. But seeing as there is no one industry standard, going with "local" has an IMO smaller value associated with it.

Secondly is "plain" datetime. This is the terminology that Temporal went with. I don't know of other projects that use this terminology. I like "plain" over "local." But I do still find it a little odd because I don't really know what's "plain" about it. The description of "plain" only makes sense relative to something else. And in this case, it's "plain" because it lacks a time zone. So in order to understand what it is, you actually need to understand what it isn't. It feels indirect to me personally. With that said, I don't find it as confusing as "local," and given Jiff's Temporal ancestry, it would make a lot of sense for Jiff to just use "plain" and gain the benefits of being consistent with Temporal.

Thirdly is "civil" datetime, which is what Jiff currently uses. It's also used by Abseil (Google's C++ standard library). "civil" is definitely not as popular as "local," and it's a bit more baroque. The main thing I like about it is that it's a bit of a jargon-y term. It means you have to stop and think about what you're doing when you reach for inexact time. The name doesn't come with confusing baggage like "local" (IMO). The name is not indirect like "plain" (IMO). And it refers to a real concept of civilian time.

Fourthly is "naive" datetime, which is what Chrono uses. I think this suffers from the same indirect downside as "plain" (naive? naive about what? in relation to what?) And, IMO, it suffers from applying a negative connotation to inexact time. But there's nothing inherently wrong with inexact time, and it is sometimes the correct thing to use. The main problem with it is that a lot of programmers have used it when they shouldn't use it, and I guess that is why it is in some sense "naive." But I don't like the indirectness or the negative connotation personally. I would pick "local" over "naive."

I think there are other choices as well. The time crate gets an honorable mention for "primitive." But I'd pick "local" over primitive.

So ultimately, my order of preference is something like:

• civil
• plain
• local

And it kinda stops there, because I don't see myself realistically picking anything else.

[jhpratt]

For what it's worth I have mulled over changing the name of PrimitiveDateTime to PlainDateTime in a future breaking release.

[tv42]

To me naive and primitive are just derogatory-sounding words without a clear meaning. They're trying to describe what they are not, instead of saying what they are.

Local time doesn't imply lack of timezone, it's often used in contrast with UTC time, without meaning civil time.

IMHO civil time is the perfect term. "Time according to local civil authorities" is, literally, what end users want: the thing that matches the wall clock.

Local time also just means your next source of confusion is local to whom. I often deal with "time over there", that may be local to them but not local to me/user, and having a lot of variables floating around saying local something has been a source of confusion. Civil time needs the same "according to whom", but doesn't implicitly make everyone assume its the user's current locale.

I've been helping a client who runs a travel booking site. When a tour starts at 9am, it means the moment when the official clocks at that locale say 9am, regardless of what timezone they are in (at time of event, at time of booking, etc), regardless of whether a daylight savings transition happened last night, regardless of whether the government passes a law that shifts their clocks by 13.4 minutes. Civil time encompasses this clearly.

[rben01]

Is it civil time, or civic?

[tv42]

I see civil be the "official term", and civic time the common typo.

https://opensource.googleblog.com/2016/04/cctz-v20-now-with-more-civil-time.html

https://www.merriam-webster.com/dictionary/civil

[rben01]

Ah, I see that in general, civic means (among other things) “relating to a city or locale”, but that “civil time” does appear to be the term of art for this concept (though were I starting from scratch I would not use “civil” in that context).

[dengelt]

So "civil time" refers to a time without a specified timezone? I would never have guessed that from the name, for me that is by far the most unintuitive option. I like naive because it contrasts nicely with the notion of timezone "aware" time (and "UnawareDateTime" would just be weird).

[BurntSushi]

The following names are effectively synonyms when used to describe a "datetime" type in a general purpose datetime library:

• civil
• inexact
• wall
• clock
• local
• naive
• primitive
• plain
• unaware

And maybe more that I'm forgetting.

I note that I personally consider the fact that "civil" requires just a little bit of thinking and examination to be an upside.

[rben01]

It's a bit long, but how about “zoneless”? Yes it is defined by what it isn't, but unlike “naive”, ”unaware”, “plain”, and “primitive”, it tells you up front exactly what it's not.

[BurntSushi]

That is an interesting name. Unfortunately, I don't think anyone else uses it. civil doesn't enjoy broad use, but at least Jiff isn't alone in using it.

[tbu-]

As a non-native English speaker, civil sounded like the opposite of military, and it wasn't entirely clear to me what was meant with it.

"naive" tells me it's unaware of something, which I kinda like, but no strong preference here.

[gulbanana]

more datapoints:

• win32 and sqlite use “local”
• ruby uses “civil”
• macos and delphi call the same concept “system” datetime