RFR: Updated section on Code Conventions.

Alex Buckley alex.buckley at oracle.com
Fri Jun 26 22:42:30 UTC 2020

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

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.

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.

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" ?


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

More information about the jdk-dev mailing list