The basic assumption when designing anything is that you can never rely on assuming that other humans "will" know.
That is exactly the kind of hidden assumption that I’m trying to fight against! If the date and the locale were both passed in as parameters, preferably just plain data, this would be a transparent function. Instead, you have to find and read through the documentation to see what kind of mischief is going on. And you have to do that every time you encounter a Java.until.Calendar.
Edit to clarify: if “locale” is some class, you have to learn that class DSL to examine it, and depend on a runtime debugger that does the same. If “locale” is just a hash map, you can examine the values without a lot of faff.
If I try to assign an int value to “3.2” will the language silently fail with null, or a round, or a floor, or a ceiling? Some level of understanding is necessary. I want it to also be reasonably explicit.
Java time library doesn’t meet that standard until Instant.
one may argue that the only correct thing to do here is a compile-time error
Once you know that “Java says X is the first day of the week,” you can make your own calculations from it with modulo arithmetic. There is no need for a class here, or for it to build a whole subsystem of locale interpretations. That should be the responsibility of a library. Maybe even the standard library, but it should not mask the core data values in the system by default.
dayOfWeek(n) should be something that you apply to a value, not something that returns a value with no args based on your locale. Or, if it does, the function itself should accept an override locale instead of assuming it from a higher level.
Timestamps are hard and maybe not the best example. It was what’s in the article though, and I’m also pretty salty about them after some recent work stuff.