RFR: Updated section on Code Conventions.

[Magnus Ihse Bursie]

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