RFR: Updated section on Code Conventions.

[Lance Andersen]

> On Jul 1, 2020, at 11:54 PM, Stuart Marks <stuart.marks at oracle.com> wrote:
> 
> 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.
> 

+1 

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

How about we keep this simple to start and keep this as an additional document in the Developer Guide Project.  If we find the need to place it in its own project later, then we can. 

I think it is more important to move forward with the updates to the style guide now that we have some momentum behind doing so.

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

+1

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


> s'marks


Best
Lance
------------------




Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
Lance.Andersen at oracle.com