RFR: Updated section on Code Conventions.

[Andrew Haley]

Hi,

On 26/06/2020 15:13, Magnus Ihse Bursie wrote:
>
> 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.

Thank you for doing that.

> On 2020-06-22 18:40, mark.reinhold at oracle.com wrote:
>> 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.

Mark's point, and I hope I'm not misrepresenting him, is that figuring
out what the coding style should be, without being over-prescriptive,
is difficult and requires a JEP. Putting non-authoritative Java style
guidelines in the Developers’ Guide risks bypassing any review
process.

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

True, but a nonexistent style guide is far better than one which in
effect constrains developers and reviewers in such a way as to make
working on the JDK worse, in terms of both the experience for the
developer and the outcome.

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

Be that as it may, it's not a reason to publish non-authoritative
style guidelines either.

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

But for that to happen, you have to have some agreement about what
then code style guidelines in a Developers' Guide should be.

-- 
Andrew Haley  (he/him)
Java Platform Lead Engineer
Red Hat UK Ltd. <https://www.redhat.com>
https://keybase.io/andrewhaley
EAC8 43EB D3EF DB98 CC77 2FAD A5CD 6035 332F A671