RFR: Updated section on Code Conventions.

[Magnus Ihse Bursie]

On 2020-07-01 07:23, Stuart Marks wrote:
>
>
> On 6/26/20 6:37 PM, Joe Darcy wrote:
>> On 6/26/2020 10:54 AM, Brian Goetz wrote:
>>> To the extent that it forms a “from the source” set of 
>>> recommendations for new language features (which are coming fast and 
>>> furious these days!), a non-authoritative guide still has 
>>> significant value.
>>
>> As a concrete example, such a style guide would provide a natural and 
>> more discoverable home for useful documents like Stuart's
>>
>>      "Local Variable Type Inference: Style Guidelines"
>>      https://openjdk.java.net/projects/amber/LVTIstyle.html
>
> Thanks for mentioning this, Joe. To this I'd add Jim Laskey's document,
>
>     Programmer's Guide To Text Blocks
>     https://cr.openjdk.java.net/~jlaskey/Strings/TextBlocksGuide_v9.html
>
> I will quibble here with Brian's intimation that these documents are 
> not authoritative. I would argue that being "from the source" implies 
> that the documents *are* authoritative. They were written by people 
> very close to the development of the features themselves, and as such 
> are in the best position to give informed advice about proper and 
> improper use, avoidance of pitfalls, recommended practices, and so forth.
>
> With this in mind, I will state that I do not think the Java Style 
> Guide belongs in the Developer's Guide. The reason is that the 
> documents have fundamentally different editorial stances.
>
> The Developer's Guide is primarily operational: it contains 
> information about how to do things, where to look, whom to ask, step 
> by step procedures to follow, tips & tricks for working effectively, 
> and so forth. It covers a wide range of topic areas. For example, one 
> tip might be
>
>     To switch branches, use 'git switch' instead of 'git checkout -b'.
>
> Git experts might reasonably take issue with this advice. However, git 
> experts might not have any opinion at all on other topics, such as one 
> that covers the proper usage of the noreg-long label on a JBS issue. 
> As such, the Developer's Guide benefits from input from many 
> individuals with a broad range of interests, each contributing bits of 
> expertise in different areas.
>
> 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?

/Magnus

> It seems unwise to put JIRA+markdown plugin improvements into the 
> critical path of delivering a style guide. Doing that might prove fatal.
>
> s'marks