Strong disagree - 'plus' is quite a good name for Joda Instant, and his alternatives are atrocious.
Certain problem domains require baseline familiarity with the subject. Far more people can recite the old "30 days has September, April, June, and November" rhyme than can explain what the words commutative and associative mean. Date math may annoy pure mathematicians but normal humans are used to working with calendars.
In the problem domain of dates, 'plus' is analogous to (but not exactly) its mathematical counterpart, and Joda's month math is almost always exactly what you want. Furthermore, plusIshRoundCeiling doesn't really explain anything; ceiling of what? The OP suggests that the cognitive dissonance is beneficial to the user. In which case it might as well be plusAsterisk or plusDontForgetToReadTheDocumentation.
The problem with plusGoReadTheDocs et al is that all problem domains have little edge cases like this. Excepting pure math, every single plus method is going to have notes. It'll be worse than those useless Prop 65 warnings in California.
Joda did this one right. Date math is simply not associative or commutative. Thankfully, most people are familiar with calendars and have some intuitive sense of this already. Littering the API with special hints doesn't help.
Although I think your comment here rather underestimates mathematicians :) Regular people are the ones who are only used to thinking in real numbers or integers. While some may be familiar in a practical way with how dates and times work, they would probably struggle to rigorously define the algebra of time math where associativity and commutativity don't hold. Mathematicians will be familiar with areas like abstract algebra and group theory and very capable of understanding the concept that date math is not normal integer arithmetic.
Either way though, I agree the plus operator works great here given the inherent weirdness of how we have structured human time, and everything the author is proposing is worse. Joda handles the trickiness of dealing with time far better and in a much less error-prone way than any other library I've seen.
It is interesting that many of the comments have suggested that JodaTime does what a "normal person" would expect in most of these odd cases, whereas you are pointing out that advanced mathematical concepts can define an algebra where associativity doesn't apply. Almost opposite points! But well taken.
One thing though: I think I was clear that I like Joda Time. It does handle these things better than most libraries. That is what makes it interesting to discuss. I could write a fun article picking apart some awful library, such as the old Java default library, but what would be the point.
Yeah ironically I think STEM non-mathematicians (STE?) in these comments seem to have the most difficulty with the concept of “month” because they try to conceive of it as a numerical quantity of days rather than an abstract concept in its own right as a pure mathematician would recognize.
Certain problem domains require baseline familiarity with the subject. Far more people can recite the old "30 days has September, April, June, and November" rhyme than can explain what the words commutative and associative mean. Date math may annoy pure mathematicians but normal humans are used to working with calendars.
In the problem domain of dates, 'plus' is analogous to (but not exactly) its mathematical counterpart, and Joda's month math is almost always exactly what you want. Furthermore, plusIshRoundCeiling doesn't really explain anything; ceiling of what? The OP suggests that the cognitive dissonance is beneficial to the user. In which case it might as well be plusAsterisk or plusDontForgetToReadTheDocumentation.
The problem with plusGoReadTheDocs et al is that all problem domains have little edge cases like this. Excepting pure math, every single plus method is going to have notes. It'll be worse than those useless Prop 65 warnings in California.
Joda did this one right. Date math is simply not associative or commutative. Thankfully, most people are familiar with calendars and have some intuitive sense of this already. Littering the API with special hints doesn't help.