RFR: Updated section on Code Conventions.

[Jesper Wilhelmsson]

> On 27 Jun 2020, at 00:42, Alex Buckley <alex.buckley at oracle.com> wrote:
> 
> The CfV for the Developer's Guide Project said: "The OpenJDK Developer's Guide is intended to contain tutorial style texts that give examples and step-by step directions for common parts of the development process. Strict rules for OpenJDK development are better suited to a process JEP. The development of such a JEP is outside of the scope of this project but will be developed as part of a separate effort in parallel."

That is only part of the mail. It also linked to the OpenJDK wiki with a reference to the process related information that has been posted there.

> With that in mind, some thoughts:
> 
> 1. The OpenJDK Bylaws define "social infrastructure" -- roles, voting, groups, projects. Where is the definition of "technical infrastructure" -- repositories, bug trackers, mailing lists, test fleets? Answer: Locked up in the current OpenJDK Developer's Guide. It seems to me that a good start would be: throw all the chapters in the current Guide up in the air, and catch only the ones which let you write a dry, factual manual about the technical infrastructure. Such a manual relies on the social infrastructure from the Bylaws, notably the idea of a Project. The manual is not "normative" in the sense of "using wise judgment to establish a standard that people must follow". Accordingly, it does not describe processes (e.g. CSR) or conventions (e.g. code style, or how-many-changesets-to-become-Committer). Nor is the manual "informative" in the sense of giving tutorials, discussion, or rationale about a normative artifact. It's definitional, like the Bylaws.

There are parts like this in the current guide and there will be more of this kind going forward. The mailing lists recently got a new description [0]. It hasn't been released to the webserver yet, but it's in GitHub.

> 
> 2. Now turn to normative processes that use the technical infrastructure: filing a bug, producing and shepherding a changeset, ensuring compatibility using CSR, etc. For these topics, there is established behavior that every OpenJDK Participant must follow. It seems to me that this is what the CfV really wanted to document with "tutorial style texts". By all means present the process of filing a bug as a tutorial, but don't pretend it's merely a "non-authoritative suggestion". There is plainly a right way, a norm, an authoritative suggestion when it comes to filing a bug, or formatting a changeset comment, or thinking about the source/binary/behavioral compatibility of a change.

I agree that there is "a right way" to do many of these things, and yes this is the kind of texts that I referred to as "tutorial style texts".

> 
> 3. Now turn to informative content that every OpenJDK Participant is free to ignore without consequence. I think you're saying that this could include non-authoritative suggestions about the formatting of Java source code in an OpenJDK repository. However, I agree with Mark: any document connected with Oracle that concerns Java code formatting will be taken as normative, authoritative rules by a broad swathe of the worldwide Java developer community. I can tell you 20 ways that people will interpret your content as "Oracle's Official Java Coding Guidelines". (Example: "In this article on $DEVELOPER_NEWS_SITE, we examine Oracle's new coding guide, and see how it compares with guides from Google and Alibaba!" -- the writer is incentivized to get views, not to make Magnus happy with how the guidelines are characterized.) Is there some other content that can uncontroversially be labelled as informative? "A Year In The Life Of A HotSpot Bug" ? "Advice On Starting A Port, as told by Dalibor Topic" ?

I'm not sure that I have any good examples of "informative content that every OpenJDK Participant is free to ignore without consequence", that would as you exemplifies here be just stories. I'm not even sure how to interpret the word "informative" here since our process JEPs which are clearly meant to be followed strictly are "informative JEPs". However I don't think that the coding style guide fits in this category because it's not a document that can be ignored without consequence. Even if it's not meant to be strict rules, it's still meant to be followed where there are no good reason to do something else. This is basically at the same level as many of our other guides for how to do things like filing a bug, backing out a changeset, problemlist stuff [1], or the JBS Label Dictionary [2] all of which are things I intend to move into the Guide in some form. Or how to use noreg-labels in JBS (which has been in the Guide since the start [3]). The JBS Label Dictionary was actually the page that started this whole discussion that eventually lead to creating the Developers' Guide Project.

I agree that there will be people taking the style guide as normative regardless where we publish it, but I don't think we should allow peoples misconceptions to decide how or where we publish our documentation. "we" and "our" here by the way refer to the OpenJDK community, not Oracle. The Developers' Guide is an OpenJDK project, not an Oracle project. Anyone calling these "Oracle's Official Java Coding Guidelines" would just be plain wrong. The author of the text who is also contributing it isn't even employed by Oracle. Oracle's official Java coding guidelines are here [4]. This is the style that all Oracle employees should use for their Java code unless we have our own style guide.

I'm sure some blog or article will present comparisons like the one you mention. If they call it Oracle we should correct them. Besides that I don't see any harm in an article comparing this to the Google and Alibaba guides. If anything it will just bring more traffic to our guide and spread the word that this is becoming a document worth paying attention to. (Hopefully that won't happen until the rest of the Guide has more content.)

/Jesper

[0] https://github.com/openjdk/guide/blob/master/src/mailingLists.md
[1] https://wiki.openjdk.java.net/display/HotSpot/HotSpot+How+To
[2] https://wiki.openjdk.java.net/display/HotSpot/JBS+Label+Dictionary
[3] https://openjdk.java.net/guide/changePlanning.html#noreg
[4] https://www.oracle.com/java/technologies/javase/codeconventions-introduction.html

> 
> Alex
> 
> On 6/26/2020 7:13 AM, Magnus Ihse Bursie wrote:
>> Mark, Andreas, Jesper,
>> First of all, I think this question is of far too much importance to discuss only for the reviewers on guide-dev, so I'm widening the scope to include jdk-dev. I am certainly not alone in thinking that having the Style Guidelines was a major part of what the Developer's Guide Project was all about.
>> Secondly, for some reason, I have not gotten any further emails from this code review. :-( Possibly it's related to the many hiccups of the ojn mailing list server lately. I have tried quoting part of Mark's comment here by copying it from GitHub. I apologize if the formatting is a bit odd due to this.
>>> No matter what we say about these documents merely being suggestive guidelines, at least some people will treat them as normative and authoritative, and use them as the basis for arguing one way or another.
>> I do not agree that this is a valid argument. We can't claim that we should not publish guidelines, since some people will not understand what "guidelines" mean. If you are serious about this argument, then we can just as well shut down the entire Developer's Guide, since it's all about non-authoritative suggestions.
>> The fact that "some people can misunderstand" is hardly ever a good reason not to provide information that is highly useful to the vast majority who do not misunderstand.
>>> A Java style guide published in the OpenJDK Community will also be used by people in the broader ecosystem who will never contribute to the JDK, but who?ve been asking us for years for an updated style guide for use in their own work. We should therefore try to take extra care with it.
>> Oh, really? We missed that train years ago. If we had published updated style guides when everybody was screaming for it, we could have had an impact on the wider Java community. But we did not, and our official style rules slid into oblivion.
>> That crown position has been taking mostly by Google's Java Style Guide [1].
>> We might be able to restore our position as a beacon to the rest of the Java community, or we might not. I'm not even sure if it is a good thing for the OpenJDK community as such if our internal processes are governed in fear of making a mess for a group of unknown outsiders.
>> And even if we do think it is desirable, for every year we wait until we publish a guide, the harder it will become to create a new, globally recognized, normative style guide.
>>> So, I don?t think code style guidelines belong in the Developer?s Guide, even if they are just ?guidelines.
>>> [...]
>>> An authoritative document, by contrast, should be fairly stable, and changes to it should be subject to broad review so that it represents a rough consensus of JDK contributors rather than that of a smaller group of Guide contributors.
>>> [...]
>>> Fortunately we already have an established means of building consensus around authoritative documents, namely the JEP process. I suggest that code style guides be published as informational JEPs, alongside existing prominent JEPs such as those for the release process, incubator modules, and so forth.
>> First of all, I wholeheartedly object to the view presented here that the JEP process is an inclusive and democratic way of bringing the OpenJDK community forward.
>> On the contrast, JEPs tend to mostly be authoritative documents written by the authors and endorsers, and feedback from the community is all-too-often ignored. There is no way an outsider can submit a patch to a JEP and have it reviewed, discussed, and/or accepted. Instead, anyone objecting to a JEP will need to communicate their sentiment on the mailing list, and watching the authors of the JEP get inspired by it, or ignore it, all at their own will. There is no voting about JEPs. Non-informational JEPs give the wider community a choice to come with "reasonable objects", but that is only a binary choice on a completed proposal, and it does not even apply to Informational JEPs that are supposed to be continuously updated.
>> I do not want to go into a discussion if this is a method that works well for planned features in the JDK (let's assume so for now, and save that question for a rainy day!). But it is certainly not a process that is any more inclusive than having the Style Guide as a project on Github. On the contrast, here any OpenJDK Member is free to publish a patch, and have it discussed, in the open, by all other members. If anything, the error in this process lies in the unfortunate fact that not all OpenJDK Members were made initial Reviewers of the Guide Project.
>> Finally, I want to bring notice to the fact that Andreas' proposal for a Style Guide was ready, with basically the same contents that are being proposed here, in 2015. That is 5 years ago! For all this time we have been without any written document to guide us, formal or informal. If you believe a JEP had been the best way forward in this issue, as the JDK Team Lead you have had ample of time to get that ball rolling.
>> If you want to create an Informational JEP, with an authoritative style guide, fine, go ahead. But, in the meantime, do not block the Developer's Guide from having a written document to help and support the actual developers that struggle everyday with trying to write good, readable code, or for that matter, reviewers who are in need of guidance of what to accept or reject, or who have to repeat, over and over again, to newcomers how code is supposed to look to be accepted.
>> The lack of this document does not mean that "anything goes". It just makes the knowledge invisibly buried in the heads of a few developers and reviewers, were it cannot be easily shared, and where it steals precious time from said developers in repeating these rules over and over in reviews.
>> My suggestion to resolving these conflicting views on what the code style guideline should be, by adding a large header to the document with something like: "This is a non-authoritative document, and is considered an interim solution. An Informational JEP with the purpose of being a formal, authoritative document for the Style Guide is being worked upon, and will fully replace this document when it is completed."
>> /Magnus
>> [1] https://google.github.io/styleguide/javaguide.html