<i18n dev> RFR: 8276348: Use blessed modifier order in java.base

[David Holmes]

On 4/11/2021 12:14 am, Pavel Rappo wrote:
> On Tue, 2 Nov 2021 16:30:56 GMT, Pavel Rappo <prappo at openjdk.org> wrote:
> 
>> This PR follows up one of the recent PRs, where I used a non-canonical modifier order. Since the problem was noticed [^1], why not to address it en masse?
>>
>> As far as I remember, the first mass-canonicalization of modifiers took place in JDK-8136583 in 2015 [^2]. That change affected 1780 lines spanning 453 files. Since then modifiers have become a bit loose, and it makes sense to re-bless (using the JDK-8136583 terminology) them.
>>
>> This change was produced by running the below command followed by updating the copyright years on the affected files where necessary:
>>
>>      $ sh ./bin/blessed-modifier-order.sh src/java.base
>>
>> The resulting change is much smaller than that of 2015: 39 lines spanning 21 files.
>>
>> [^1]: https://mail.openjdk.java.net/pipermail/core-libs-dev/2021-November/082987.html (or https://github.com/openjdk/jdk/pull/6191#pullrequestreview-794333365)
>> [^2]: http://mail.openjdk.java.net/pipermail/core-libs-dev/2015-September/035217.html
> 
>> _Mailing list message from [David Holmes](mailto:david.holmes at oracle.com) on [core-libs-dev](mailto:core-libs-dev at mail.openjdk.java.net):_
>>
>> On 3/11/2021 9:26 pm, Pavel Rappo wrote:
>>
>>> On Tue, 2 Nov 2021 20:34:44 GMT, Martin Buchholz <martin at openjdk.org> wrote:
>>>>>> Pragmatically, fix the script to ignore those keywords on comment lines. Learn Perl, its just a regular expression pattern match and replace expression.
>>>>>
>>>>>
>>>>> I understand in principle how to modify that script to ignore doc comments. The thing I was referring to when said "btw, how would we do that?" was this: not all comment lines are prose. Some of those lines belong to snippets of code, which I guess you would also like to be properly formatted.
>>>>>> But having seen several reviewers be unmoved by the difference, the real pragmatic view is to ignore the English.
>>>>>
>>>>>
>>>>> I'm sorry you feel that way. Would it be okay if I made it clear that those two words are not English adjectives but are special symbols that happen to use Latin script and originate from the English words they resemble? If so, I could enclose each of them in `{@code ... }`. If not, I could drop that particular change from this PR.
>>>>
>>>>
>>>> The blessed-modifier-order.sh script intentionally modifies comments, with the hope of finding code snippets (it did!)
>>>> Probably I manually deleted the change to Object.java back in 2015, to avoid the sort of controversy we're seeing now.
>>>> I don't have a strong feeling either way on changing that file.
>>>> I agree with @pavelrappo  that script-generated changes should not be mixed with manual changes.
>>>> I would also not update copyright years for such changes.
>>>> It's a feature of blessed-modifier-order.sh that all existing formatting is perfectly preserved.
>>>
>>>
>>> One more thing. Please have a look at this other line in the same file; this line was there before the change https://github.com/openjdk/jdk/blob/465d350d0b3cac277a58b9f8ece196c1cde68e80/src/java.base/share/classes/java/lang/Object.java#L49
>>> So before the change, the file was somewhat inconsistent. The change made it consistent. **If one is going to ever revert that controversial part of the change, please update both lines so that the file remains consistent.**
>>
>> Line 281 is (was!) consistent with line 277 because it is distinguishing a synchronized "static method" from a synchronized "instance method". There was no need to make any change to line 281 because of the blessed-order of modifiers as defined for method declarations! This text is just prose. Now for consistency you should change line 277 to refer to a "non-static synchronized method" (as "instance synchronized method" would be truly awful).
> 
> Thanks, David. You've provided a clear and convincing argument, and I can see the inconsistency I introduced. I can revert that particular piece back if you think that it would be appropriate.
> 
> That said, this line will have to be filtered out every time the script is run. I could probably provide a more involved script that harnesses the power of AST (com.sun.source.doctree) to try to filter out prose, but it would be impossible to beat the simplicity of the current script; and simplicity is also important.

Given this is prose, the adjectives should be separated by commas: "a 
synchronized, static method", and "a synchronized, instance method". 
Does that avoid the problem with the script?

>> Line 49 places "static synchronized" in code font, implying that it is referring to the actual method modifiers and as such using the blessed order is appropriate. Line 49 does not need to be "consistent" with line 281. If line 49 used a normal font so the words "static" and "synchronized" were just prose then either order would be perfectly fine in terms of English language, but then you could make a case for having it be consistent with line 281.
> 
> I've been always having hard time with modifiers being not enclosed in `@code` in the first place; they are barely English words. Is there really a semantic difference between L49 and L281 such that it warrants the use of `@code` in the former but not in the latter case? Does `synchornized` or `static` in L281 refer to anything other than the like-named Java modifiers?

Consider this definition:

"A synchronized method is one which must acquire the monitor of the 
Object upon which the method is invoked, and is indicated by applying 
the {@code synchronized} modifier to the method declaration."

Here there is a distinction** between the general notion of a 
"synchronized method" and the "synchronized" modifier. Obviously they 
are strongly related, and often could be used interchangeably, but you 
can also find places where it is more appropriate to use one over the 
other. So yes it is hard, but context can influence the choice: is this 
text referring to the general concept of a synchronized/static method, 
or to the use of the modifier? Line 49 could have gone either way IMO.

** The distinction would be more obvious if Java had an implicit way to 
define synchronized methods. So think about the concept of "package 
private" access - there is no package-private modifier so you 
wouldn't/shouldn't ever write "package private" in code font.

Cheers,
David

P.S. For the book "The Java Programming Language" the authors made a 
very conscious decision to not put the word "synchronized" in code font 
every time it was used in the text, but reserved the code font for 
specific usages. The same applies to other modifiers: static, public, 
etc. Other authors have made similar decisions.

> -------------
> 
> PR: https://git.openjdk.java.net/jdk/pull/6213
>