Plurals vs singulars in ordinals

This issue is for gathering inputs from people with an intuitive understanding of English to help us name things.

Preliminaries: we have Instant.epochSeconds, which returns the number of seconds that passed since the Unix epoch. On the epoch itself and after some number of nanoseconds that don’t amount to a whole second, Instant.epochSeconds returns 0.

Other libraries, like java.time, provide the same functionality, but with a slightly different name: Instant.epochSecond (note it being singular). We assume that the idea behind this is “the nth second since the epoch”.

However, colloquially, the nth second/etc. is the second/etc. that goes on before n whole seconds/etc. have passed. For example, January is the first month of the year, that is, the month that goes on before a whole month has passed.

Questions for the readers:

• If you see Instant.epochSecond == 1, what do you think it means—does it mean that it is the first second since the start of the epoch, or that 1 full second has passed since then?
• The same, but about Instant.epochSeconds. Does this naming seem natural, or slightly odd?
• The same about LocalTime.secondOfDay and LocalTime.secondsOfDay: do they mean the same thing to you, or do you feel the first one is an ordinal, but the second one is the count?

[cpovirk]

I recall giving some thought to this in designing some of our own time-related APIs. I don’t recall all the details, but I like the look of the post above, which reminds me of this comment from Stephen Colebourne and this other comment from Stephen Colebourne.

My take, which I think may be compatible with the previous post, but I am confusing myself as I dig through old links… 😃

• Instant.epochSecond == 1: a full second has passed
• Instant.epochSeconds == 1: probably still that, but I think I’d prefer the singular, and I might expect the plural to return a floating-point number
• LocalTime: same answers, and I’d prefer singular even more, since theoretically someone could expect “secondsOfDay” to return the total number of seconds in that day (which isn’t something that a LocalTime or even a LocalDateTime could answer, of course, but someone might expect it to)

My understanding is that the java.time people consistently used the singular for the fields of LocalTime-like objects and erred only in accidentally also using it for the one of the fields of Duration, which should have used plural. And I think that’s a good way to go.

[edit: one other link]

[PeterAttardo]

I think something else that’s worth noting is that in all cases where a 0 value exists, the unit is 0-indexed. The time components all have a :00 value, so they are all 0-indexed. Whereas there is no 0th month, 0th day of the week, or 0th year on the calendar, so they are 1-indexed. Admittedly this is a bit of a tautology, but it’s still instructive. If 0 is a valid value for secondOfEpoch, then I think that would imply it should be 0-indexed as well.