RFR: Updated section on Code Conventions.

[Stuart Marks]

On 7/1/20 1:44 AM, Magnus Ihse Bursie wrote:
>> A style guide is fundamentally different. To be useful, it must be 
>> authoritative -- as mentioned above -- and it also must be highly cohesive. It 
>> needs to have a uniform editorial voice that is adhered to consistently 
>> throughout the document. For example, it might take a prescriptive vs. a 
>> descriptive stance, or it might choose a vocabulary for recommendations of 
>> varying strength ("can", "should", "must", etc.) and use that throughout the 
>> document. As such, a style guide is not at all amenable to a "crowdsourcing" 
>> approach and must be edited by a handful of individuals. Since the editorial 
>> approach for the style guide material is so different from that of the 
>> Developer's Guide, it follows that the style guide should be a different 
>> document.
>>
>> Personally I'm agnostic to the exact process for delivering a style guide. If 
>> Mark thinks a JEP is required, then maybe that's the best way forward. But I 
>> could imagine other paths forward that wouldn't use a JEP.
>>
>> I would strongly recommend against making the style guide itself be a JEP. 
>> Today, editing a JEP with more than a page or two of text is already unwieldy. 
>> It's easy to introduce errors inadvertently, and history tracking is virtually 
>> nonexistent. 
> Are you suggesting that we should create a sibling project to the Developer's 
> Guide for the style guide(s), with different rules for engagement?

I'm mainly suggesting that the Style Guide not be a chapter plopped into the 
middle of the Developer's Guide. They seem like fundamentally different 
documents and so should be treated differently.

That said, where would the Style Guide reside? It could be in a separate OpenJDK 
Project, though that seems like kind of high overhead for a single document. A 
Project would have separate Reviewers/Committers/Authors, which also seems like 
high overhead, but maybe something like that is necessary. Or maybe it could be 
a Group. For example, recently formed groups like the CSR group and the 
Vulnerability group have their own, special rules of engagement.

Or, the Style Guide could be hosted in the Developer's Guide *Project* but still 
be a different document, with different norms around who is responsible for 
modifying and reviewing changes. If the Style Guide has a single editor, or a 
small editorial board who are responsible for updating it, and everybody 
understands this, that might work just fine. This works for code. For example, 
I'm a libraries guy, so I don't go mucking around in Hotspot without talking to 
Hotspot folks about it first.

s'marks