RFR: Updated section on Code Conventions.

[Jesper Wilhelmsson]

I'll only quote a part of Magnus' mail here because to me there really is only one question: Is the style guide an authoritative set of rules or is it a guide with suggestions?

>> 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.

I agree with Magnus here, we can't treat it as a set of rules if it isn't a set of rules. I'm totally fine with placing it in a JEP if these are rules, but that also means that everyone are expected to follow these rules, and I'm sure that will result in a lot more policing than we see today.

If the style guide is what it's called, a guide, then having it in a JEP will actually cause more damage since it will not only be a few people who mistakenly treat it as a set of rules, it will actually look like a set of rules for the vast majority of the readers. The Developers' Guide will even (at least with the current wording) say that it is a set of rules, "The formal rules and processes are described in other documents, like JEP 1 ..., or JEP 3...".

The current wording of the style guide clearly states that it's a guide with suggestions in several places throughout the text and at least everyone I have spoken to about style guides have agreed that these should not dictate a fix set of rules that may never be broken but should rather be guidelines with flexibility when needed. If this is a JEP that is flexible, how will that affect other JEPs? Is the release process also flexible?

As for the discussion about who reviews changes, I would expect anyone interested in our guidelines to be following the guide-dev list. Changes to the guide are always reviewed by at least someone - someone must actively agree to the change before it goes in. And even after the change has gone in there is an extra step where "bad changes" can be caught since the final web-based version is not pulled automatically from GitHub, but goes through "release testing" and is manually released to the webserver. Anyone can edit a JEP at any time. I think that anyone interested in our rules should be watching these JEPs in JBS as well, but still the notification only arrives after the fact and someone must actively undo the change. In both cases changes are only reviewed by people who opt-in to the process.

/Jesper

> On 26 Jun 2020, at 16:13, Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com> 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
>