RFR: Updated section on Code Conventions.
Magnus Ihse Bursie
magnus.ihse.bursie at oracle.com
Fri Jun 26 14:13:41 UTC 2020
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 .
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."
More information about the jdk-dev