RFC: 8247976: Update HotSpot Style Guide for C++14 adoption

[Vladimir Kozlov]

Thank you, Kim for very nice work.

I agree to have it in jdk/jdk/doc which we can always reference and people can see. And also track all changes.

*Structure and Formatting*

I think ordering of sectin should by importance: naming rules and commenting are more important then spacing:

. Factoring and Class Design
. Files
. Naming
. Commenting
. Macros
. Whitespace
. Miscellaneous

May be next should be split into sub-paragraphs instead of one long paragraph:

. Use bool for boolean values.
  - Do not use ints or pointers as (implicit) booleans with &&, ||, if, while.
  - Instead, compare explicitly, i.e. if (x != 0) or if (ptr != nullptr), etc.
  - Do not use declarations in condition forms, i.e. don't use if (T v = value) { ... }.

*Use of C++ Features*

I think enum, thread_local, nullptr, <atomic> could be subsection of some new section which explicitly unite them.
At first I mistakenly saw them as subsections of *C++ Standard Library* section.

You did not say anything about preferable way of fields initialization in constructors to verify initialization order 
during compilation. We did refactoring before but new code may not follow it.

What about C++ pragmas?

Example of "new code should use integral constants"?

I wish to see more embedded examples in this document but they can be added later.

Thanks,
Vladimir

On 7/22/20 2:54 PM, Kim Barrett wrote:
>> On Jul 11, 2020, at 10:56 AM, Kim Barrett <kim.barrett at oracle.com> wrote:
>>
>>> On Jun 23, 2020, at 3:32 PM, Kim Barrett <kim.barrett at oracle.com> wrote:
>>>
>>> Please review / comment on this proposed update to the HotSpot Style
>>> Guide. This is part of the work for JDK-8208089: JEP 347: Adopt C++14
>>> Language Features in the JDK.
>>>
>>> […]  Once
>>> reviewed, the finished text can be used to update the wiki, unless we
>>> decide it should be homed somewhere else.
>>
>> There has recently been a lot of discussion about where this and
>> somewhat similar documents should reside.  Most of that has been about
>> a Java Style Guide, which has somewhat different issues than this one.
>> (The HotSpot Style Guide is very focused in scope, and is unlikely to
>> have much, if any, influence on usage by the wider C++ community.)
>>
>> Proposed homes include:
>>
>> - Remain in the OpenJDK wiki.
>> - Use an informational JEP.
>> - Move to the new Developer's Guide.
>> - Move to the JDK repository.
>>
>> For some of the discussion, see comments in JDK-8208089, as well as
>> the recent thread on the jdk-dev mailing list:
>> https://mail.openjdk.java.net/pipermail/jdk-dev/2020-June/004443.html
>> https://mail.openjdk.java.net/pipermail/jdk-dev/2020-July/004461.html
>>
>> Based on that discussion, I'm planning to move it to the JDK
>> repository, in jdk/jdk/doc. That is already a place for
>> developer-focused documentation; it's the home of building.{md,html},
>> testing.{md,html}, and ide.{md,html}. I think this style guide fits
>> well with that collection.
>>
>> I think the other two wiki pages associated with the current wiki
>> HotSpot Style Guide would similarly fit well there, and I suggest we
>> move them as well.
>>
>> Comments?
> 
> I made a few formatting tweaks to account for using the approved
> markdown processor (pandoc, via make update-build-docs); I'd been
> using a different processor, and noticed some problems with the
> generated html when I switched to using pandoc.
> 
> I've also moved the files to jdk/jdk/doc.
> 
> Reducing the heading "depths" made pandoc generate a nice TOC at the beginning.
> 
> I removed the "===" separators, because pandoc wasn't producing a
> horizontal line separator for them, unlike the previous (extended)
> processor.
> 
> There were some naked URLs that needed to be surrounded by <> to be
> autolinked by pandoc, unlike the previous (extended) processor.
> 
> New webrev:
> full: https://cr.openjdk.java.net/~kbarrett/8247976/hotspot-style.03/
> incr: https://cr.openjdk.java.net/~kbarrett/8247976/hotspot-style.03.inc/
> 
> The diffs for the incremental .html aren't particularly interesting,
> since different markdown processors were used to generate them.
> 
> I'm intending to leave the move of the other two related wiki pages to later.
> 
> Hopefully this is the last of this round of edits, though I'm
> expecting there will soon be a number of requests for further changes
> from this "baseline".
>