On Wed, 21 Aug 2024 13:49:08 GMT, Joakim Nordström <jnordst...@openjdk.org> wrote:
>> Ok yes maybe "not idempotent" isn't a great term here. >> Just removing that phrase, "This method is not idempotent.", this would >> still be a helpful update. > > I want to provide advice for how this API should be used. > > The "recent period of time observed" is vague (Who's the observer? Who > decides the "recent period"? The API user or the JVM?). In essence it is the > time between two consecutive calls, but that is not very clear from the > description -- this has been seen to cause confusion. > > I hesitated to add "idempotent", but also I felt that it added something. > Without it, the rest of the sentence is basically just the same words as in > the first paragraph, so they can be easily missed. Also, the best practices > I've seen is that "getters" should be idempotent, so stating this one isn't > signals there's something to take note of here. > > Adding `@apiNote` might be enough of signal. Have updated with the tag and > removed "idempotent". > "Idempotence is the property of certain operations in mathematics and > computer science whereby they can be applied multiple times without changing > the result beyond the initial application. " So the notion of idempotency on a getter method just doesn't make sense in general and in this case in particular as you calculate a new result each time. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/20546#discussion_r1725887348
