Bikeshed thread for civil time prefix #33
Comments
|
There was a long thread we closed on this one, but we can re-open I suppose. Most libs do local, and that thread had a strong vote for local, but I personally HATE it, and as of right now I"m championing :-). I think Plain is much more clear to the user. I would also be okay with Civil. I don't want local because it implies a location, and that's exactly what these types DON'T have. |
|
I guess my way of working would be to have an open thread for issues that seem contentious and haven't yet been locked down (i.e. gotten committee consensus). That's why I opened this. It's just a personal style of working though, so whatever works best for you as the champion. Also, it's good to get the reasoning for "not |
|
Yeah, let's keep this thread open so folks have a place to weigh in. "Plain" seems to be obvious to the uninitiated, but I will perhaps ask a few colleagues who are not date-time nerds and see what their reactions are. 😄 I can tell you, though "Local" makes sense as established ISO-8601 terminology, I've had to tell many people over the years that "it doesn't mean local to the computer or the user, it just means local to someone somewhere". Usually this gets a groans and moans reaction... So it's teachable, but not intuitive, in my experience. Also, it's confusing when other APIs have already appropriated the term "local" to indeed mean "local to the computer". For example, in .NET we have |
|
fwiw... coming from a joda background, i initially liked the |
|
I asked two different co-workers who are uninitiated to this space, and they both found While this is quite a small sample size, I do see their point. One may not be accustomed to seeing the word "Civil", but it tends to invoke the need for a Google or Wikipedia search, rather than assumption. By the way, both did say "why can't you just call it |
|
I'm +1 for |
|
to my (non-native speaker) ears and mind... I just wonder why we need to come up with something new, knowing, that it will probably lead to discussions (see already two threads in this proposal ;)) when we could be saying, well it's called |
|
FYI - We switched it to Civil in the readme. We can keep discussing though. |
|
"civil" could mean "nonmilitary", or "polite" - I'm not sure it's the best name. I personally prefer "local", but I understand the wrongly-implied location in that. |
|
Can you point us to the thread where you got the data points between Local versus Civil? I'm interested to see how representative that was. I'm assuming we have also explored not having a prefix at all too? Can you help me understand the challenges (for DateTime and Time, not Date)? A few thoughts off the top of my head:
I'm not sure if this qualifies as bike shedding. Date/Time is going to be largely used and I think that it matters how explainable they are (e.g. are we going to need to clarify what Civil means everytime we introduce Date/Time in tutorials?). Specifically, it is unclear to me the mental model and the relationship between Date and CivilDate (e.g. which one should I use? if the distinction is the "global vs local" property, than should Time and DateTime be the "global"-equivalent of the non-civil dates/times). |
|
@samuelgoto - understand that with this proposal we would encourage a departure from using the existing The previous thread was #11. As to removing the prefixes:
That said, if they all use the same prefix, that also conveys a shared set of behaviors (having no time zone or relationship to a point on a timeline). So there are advantages to having a prefix. I'm not too worried about military time aspect. Pretty much all other time APIs are based on 24-hour clocks. Do you have any alternative suggestions? |
|
Just to join in on an old discussion :) I think the common prefix is essential, however, I'm still not a big fan of "Civil". I keep thinking of "civilian" (as opposed to military as discussed above) or civilized. Each time I see it, I have to actively think about its meaning. I currently don't have a better suggestion, and I'm more fond of the |
|
As an non-English speaker, I have no strong opinion on the prefix. But maybe we could use simple words without same prefix: CalendarDate or CalendarDay |
|
Mild 👍 to When noodling around this space earlier, I used |
|
Nobody's voting for |
|
Hello World! Lots of time has passed, and things are starting to pick up steam with the this proposal again. @maggiepint and I have had a lot of discussions about this naming, and I think we've come up with a better alternative. First, let's reiterate some of the rationale behind the current "civil" name:
We originally chose So, I'd like to retract my vote and for
Each of these is exactly what they claim to be. A Also, I think "simple" is friendlier than alternatives like "basic" or "naive". As developers, we strive to keep things simple, but we often see "basic" as a watered-down version of "advanced", and "naive" seems just insulting (sorry python). So, do you love it (👍) or hate it (👎)? |
|
Simple would be a good name if the opposite was Complex. It seems to me what you're really looking for is Unzoned, because that's the fundamental difference between these functions and their counter-part Instant and ZonedInstant. Isn't it? If the above is true and Unzoned sounds "weird", it's important to ask if is the name or are the functions themselves that sound/look "weird"? Naming is usually hard, but when it's that hard, it's usually a flag that something is wrong and it's good time to take a step back and rethink the design... |
|
There is nothing inherently "simple" about these types. Its a meh prefix, like "base", "basic" or "default" used when you can't think of anything better. Similarly, there isn't anything especially "plain" about the date - its a date, and a date can't be plain or non-plain. "Civil" is no better, as few are aware of the concept of "civil time". As has been seen, "military" is often seen as the opposite. "Unzoned" is negative. It is never a good idea to name classes in the negative, particularly one as important as The only other prefix I've ever seen which doesn't completely suck (like every other one in this thread) is "Iso", as in As a reminder, in 18 years of Joda-Time I never received any feedback that "local" was confusing. Its such a key topic and class that it becomes widely used so quickly that the meaning becomes embedded in developers very quickly. All the concerns about dual meanings or confusion are simply not borne out in my experience. Consistency across Java and JS would be incredibly valuable to the industry. Please put personal preferences aside and look at the bigger picture here. Finally, I reread #11. In my opinion, any neutral observer would say that the discussion was clearly in favour of |
|
First, thanks for our feedback Stephen. As always, it is greatly appreciated. With regard to the confusion around the term "local" in Java time APIs, here is at least one example. I'm sure I could locate others. In the .NET space we've encountered this with NodaTime also, example here, despite having clear guidance in the user guide. If we chose "local" as the prefix in ECMAScript, we would probably need wording such as to distinguish local in this context meaning timezoneless as compared to other places in the spec where it means belonging to the local computer. The main areas being 20.3.1.7: I'd be very interested if you have some thoughts about how to reconcile the terminology in a way that is consistent? |
|
On the first point, people make mistakes with all APIs, they learn and they move on. The concepts here are not particularly hard for anyone willing to think a little. The biggest problem is focussing on On the second point, you are moving the platform from a world-view based solely on instants to one based on specific types. Those methods/concepts are not wrong, just from a different world view. (Hence use of "time" in APIs that should use "instant", the same problem is found in Java.) On 2.0.3.1.7 and 8, I don't really see the problem. Those methods provide the ability to convert from a UTC millisecond instant to a "local millisecond instant" (t-local). If you took that "local millisecond instant" and sent the value across the network to another machine and converted it back to UTC there, the UTC millisecond would probably change (as the machines would have different time zones). ie. the result of As such, I consider those methods to be entirely consistent with using a "Local" prefix, and in fact help make the case for doing so. |
|
Dropping my 2 cents (as mainly a Java dev) - found this thread looking for an equivalent of LocalDate for JS. At a glance, the |
|
I'm coming around to "local". While some may be confused at first about it not being related to the local time zone, we can address that in documentation. update: Me calling for renaming was premature. Sorry for that. We can keep things as-is until settling the debate. Thanks. |
|
Maybe it's because I'm not a native speaker, but even looking at the dictionary, I don't see how Reading all the discussion here, none of the prefixes except |
|
After reading all recent comments, I would like to choose Though As a non-English speaker, I hope you also notice the translation problem. The confusion may spread to translations. And, the confusion may be much serious in different languages than English. For example, when you see
Use |
|
@hax - I assume your argument applies to documentation and discussion of the concept - not to the keyword itself. I know of no cases where a compiler understands translated names of language keywords. |
|
FWIW, at the TC39 committee meeting last week, we did not particularly debate naming because it's not critical for Stage 2 - but it will be for Stage 3. I did not personally find that anyone there seemed to have a problem with "Civil" naming that we currently are using. I plan to write up a matrix describing the different options, pros and cons, prior usage, and other items that have been brought up on this thread and elsewhere. That should help us come to a final decision. |
|
Reading the comments on various threads, it is clear that "civil" has been interpreted in two distinct ways by people:
The result was a suggestion to have I think both are perfectly reasonable approaches to a naming scheme in theory - they just focus on different aspects of the date/time concept - absence of time-zone information vs which calendar system is being used. So why do I favour the former? The first reason is that absence of time-zone information on some classes is the most important aspect when initially learning the API, and later when communicating with colleagues (Ubiquitous language). In particular, because so many other date/time APIs operate "on the cheap" with a single all-in-one class, it can require a little bit of re-educating to see why less information (no time-zone) is actually more useful. Learning that they do not have a time-zone is enough for most people, who have no particular need to dig deeper. But the philosophy behind it is that they sit on the local time-line - a time-line that is not anchored to a specific instant. Most people never need to consider this, but as API authors it is important to have a coherent underlying structure and philosophy that the API builds on and exposes. The second reason is that the calendar system really isn't that important a piece of information. Now I know this is heresy for some, but the harsh reality is that the Gregorian calendar dominates the globe. To avoid some of the contentious aspects of this, I generally refer to the calendar as the ISO-8601 calendar system (which is proleptic Gregorian). Other calendar systems can be built on top of an ISO base, either as wrappers or localization. Naming the set of classes after something that an unquestioned fact for most of users (the calendar system) isn't the best option IMO. Instead they should be named after the concept that really distinguishes them from the other classes, which is which time-line is it on (aka, the presence or absence of the time-zone). As a final point, a key test for any naming approach is how to name the methods In summary, JSR-310 chose local time-line vs zoned time-line as the primary axis of the API, and thus got Local vs Zoned. And the result was the creation of a ubiquitous language that developers could use and express the concepts they needed to express. I simply don't think Civil implies the time-line aspect clearly enough. |
|
I've just read the current spec and essentially you've ended up with 80% of JSR-310 but chosen a different name for the key concept. Given the I also note that the spec does not include I won't repeat the explanations for the |
|
@jodastephen interesting. Could you please make a PR against civil.md documenting your thoughts so everyone could see more clearly what was missing and perhaps move forward and make a better choice? |
|
@jodastephen after initially agreeing with your comment, I found #79 to be an informative read on why My current concern, after looking through various issues here, is that I have the impression that none of the champions for this proposal have much experience with non-Gregorian calendars. More to the point, I get the impression that everyone involved has an American/European background. I'm American myself (and have no experience with other Calendaring systems), but it seems like this proposal needs to cultivate the involvement of people actually living with other calendar systems. Even acknowledging that version 1.0 of this spec will only target a Gregorian-esq calendar (which is understandable), it seems like a lot of research needs to be done to understand how it will be extended in the future. The statement in the README that "other calendar systems are out-of-scope for this proposal" seems rather ridiculous. I have a hard time believing that you can "fix PS: I can imagine someone countering by saying that Java is used around the world. I'll preempt that hypothetical comment by saying that that would be missing the point. Yes you can use Java anywhere in the world, but you don't have to. |
|
@thefliik some great points here, that said, about the whole multiple calendars thing, I am still quite unsure. While I agree that it’s one of the major flaws of FWIW, people are exploring the possible interactions between the different objects in this proposal and the different P.S. While I grew up in an increasingly English-centric environment, I have had some experience with the Saka Calendar (https://en.wikipedia.org/wiki/Indian_national_calendar) and am in regular contact with people who follow that calendar much more closely, so I volunteer to help address any concerns with relation to how this could possibly work in a different calendar system. |
if i wanted to integrate Saka-calendar with javascript, the cost-effective solution is to expose 3 static-functions that manipulate isostrings: function getGregorianFromSaka(isostringSaka) {...}
function getGregorianToSaka(isostringGregorian) {...}
function getSakaAdd(isostringSaka, durationObj) {...}
var date;
/*
* example to add 1 saka-month to gregorian-date "2020-01-15"
*/
date = "2020-01-15";
date = getGregorianToSaka(date); // saka "1941-10-25"
date = getSakaAdd(date, { month: 1 }); // saka "1941-11-25"
date = getGregorianFromSaka(date); // greg "2020-02-14"its cost-effective because it requires zero-coordination with this proposal or tc39. this same design-pattern can be applied to other calendar-systems (e.g. lunar). |
|
If you believe that’s the best solution, then are you planning to publish a library that does it, and persuade everyone who’s currently convinced they need a builtin solution that your library is sufficient? |
|
i did propose it as an alternative in issue #53. at the time, the 5 proposed static-functions did everything the 5 classes CivilDate, CivilDateTime, CivilTime, Instant, and ZonedInstant (at the time) did. with far less spec-work. |
|
The quantity of spec work isn’t really important, though - shipping the best solution for the most use cases is. Static functions that manipulate strings are certainly sufficient for some use cases, but are wildly insufficient for many others - so that suggests it wouldn’t be a good fit. |
|
@ljharb @kaizhu256 while a bunch of 3rd party libs like these would be useful and would “just work:tm:”, I guess it’ll still be useful to add functionality to get the ISO string in an alternate calendar system in the spec itself, but I do agree that it makes sense to address that in a separate, later proposal, perhaps to ECMA 402 since I’m personally a huge critic to scope creep. But I’d love your feedback. |
|
@thefliik and others - I note the crossover between issues of naming and issues of calendar systems again. (For those not aware, I'm the author of Joda-Time and JSR-310 (java.time.*) which have been influential in the design space for dates/times for 20 years) Firstly, it is certainly true that the Gregorian/ISO calendar system is the de facto world standard, and pushed into greater importance by the internet. It is vital to be able to format/parse a localized date, but this is a localization issue, not a class design one. Why is it a localization issue? Well, when you go to a website and buy access to a service for a month, the length of the month isn't determined by what calendar system the user likes to see dates in. If it were, the user might only get 5 days of access to the service (Coptic calendar has 12 thirty day months followed by a 5 or 6 day month). As such, it is always the case that business logic must be written against a single fixed calendar system, and again that is almost universally going to be the Gregorian/ISO one. As such, the "date without time-zone" object exists primarily to represent just the concept of a date, not the date in any particular calendar system. Thus, the "date without time-zone" object could be satisfied by a count of days from an epoch. However, since there is one dominant calendar system in the world, and it is much more convenient for humans to deal with year/month/day than epoch-days, the best representation is actually the Gregorian/ISO one. Given all this, it is wrong to name the "date without time-zone" after the calendar system. Because, the use of Gregorian/ISO is very much a secondary concern. Ultimately, the naming point that actually matters is the "without time-zone" part. And ISO-8601 used the term "local time" here over 20 years ago. TLDR: The pure way to model a date is a count of "days from 1970" with years/months/days being entirely about localization, but for pragmatic/practical reasons it is more useful to the vast majority of users to define the class using years/months/days in the Gregorian/ISO calendar. The naming of a common prefix for classes without time-zone is a completely separate problem. |
|
@ryzokuken civil.md document only cover the prefixes "civil", "local" and "gregorian", but not mention all other options in this issue and comments: "unzoned", "plain", "floating", "simple", "basic", "naive"... I hope we remember the lesson of "globalThis" and give a full documentations for all possible names and ask the community for feedback, before too late. Especially "unzoned". Search the whole thread and you will find most support it. The only disagreement was coming from @jodastephen: "Unzoned" is negative. But when explaining the concept, we include Stephen always use "date without time-zone", so the concept is essentially "negative". Programmers can not really understand the concept without time-zone. Personally I don't see any aspect that "civil" is superior to "unzoned". |
|
@hax I understand where you’re coming from, and realize that you might be disappointed with the current state of civil.md. Could you please make a PR to civil.md documenting your thoughts around the unzoned prefix, possibly even the other options that you think have not received appropriate attention? AFAIK, ignoring certain alternatives was never the intent. Thank you. Also, I’m reopening this issue since there’s obviously something actionable in here. Let’s close this once we have reached a final prefix that works for most if not all parties. |
|
Throwing in my opinion as a random person who is eagerly awaiting proposal-temporal: It'd be ideal to just go with "Local" because that's the common terminology that already exists for the concept. I agree that "Local" initially seems like the exact opposite of what it represents. I have mostly managed to convince myself that it kind of makes sense when I squint and think of it as abstractly referring to a local date for any/every arbitrary location. But if I was naming the concept fresh, I'd vote for "Plain" or one of the other options before "Local". But "Local" is the prefix that already exists, and it doesn't cause any real problems despite arguably being oddly named. You learn it once and then it's too useful and too simple to forget. And many developers have already learned it thanks to the success of the joda-time, java.time and other libraries based on them. "Local" is well known enough that if Javascript ends up using "Civil", the documentation should have prominent notes clarifying that a "CivilDate" is the exact same thing as a "LocalDate" in other languages. Think of it this way: If Javascript goes with "Local", that will likely become what future languages choose without much debate because the familiarity of "Local" will be overwhelming at that point(it's a relatively rare programmer who is unfamiliar with both Java and Javascript). If Javascript goes with "Civil", suddenly it's the wild west and every new library will be forced to debate if it should join team "Local" or "Civil"(where it will inevitably be decided that both are terrible and "Gregorian" is the one true prefix). Is "Civil" really enough of an improvement over "Local" to make it worth being different? |
|
I am concerned that the word "Local" is too similar to "Locale" as in i18n. We will have methods like Also, FYI, JavaScript is not the first language to use "Civil"; C++ Abseil (#139) beat us to it. |
|
With respect to the Gregorian / non-Gregorian calendar comments, I suggest they are discussed in their own thread: #31. |
|
@ryzokuken Not sure how PR should be -- I can add some pros/cons about |
|
@hax and a PR would be a great place to discuss the new prefix and if it makes more/less sense than the current choice. |
|
Prefix it with "Hard", i.e. HardDate, HardTime, HardDateTime. Just because dates are hard. |
|
Another way to think about |
|
This has been solved. We’re nit prefixing, but namespacing in the Temporal global. |
|
@pipobscure Hope the proposal repo could be updated soon. 😃 |
and others
Currently the "civil time" types are prefixed with
Plain. This is a bit confusing and unclear to me, so I thought it would be worthwhile to start a thread exploring alternatives.To be clear, this kind of bikeshedding is not a big issue or blocker, and hopefully will not be too frustrating for the proposal authors. But I think it's a discussion worth having.
Some alternatives:
PlainCivilLocal(I think this is what they were originally called, and I agree it's probably bad)Floating?Unzoned?The text was updated successfully, but these errors were encountered: