RFR: Updated section on Code Conventions.
Magnus Ihse Bursie
magnus.ihse.bursie at oracle.com
Wed Jul 1 08:44:03 UTC 2020
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"
> Thanks for mentioning this, Joe. To this I'd add Jim Laskey's document,
> Programmer's Guide To Text Blocks
> 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
> It seems unwise to put JIRA+markdown plugin improvements into the
> critical path of delivering a style guide. Doing that might prove fatal.
More information about the jdk-dev