RFR: Updated section on Code Conventions.

[Jesper Wilhelmsson]

On Sun, 31 May 2020 20:14:44 GMT, Andreas Lundblad <github.com+5994243+aioobe at openjdk.org> wrote:

> Pull request for adding code conventions.
> 
> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html

Thank you for contributing this style guide. This is something that many have been asking about.

src/codeConventions.md line 7:

> 6:
> 7: This is a set of code conventions for for JDK Release Projects in the OpenJDK Community. Other OpenJDK Projects, and
> projects outside of OpenJDK, are welcome to adopt these guidelines as they see fit. 8:

This code convention is for Java code only, right? I'm thinking that we want to have a separate style guide for C++
code, and there will be one for markdown as well since it's used in several places in the docs. For this reason I think
it would be better if the actual style guide was on a separate page and this main style-page only has the Motivation
and Guiding Principles together with links to the three separate sub-pages.

src/codeConventions.md line 41:

> 40:
> 41: ## Motivation{#motivation}
> 42: Code that looks familiar is easier to understand and therefore also easier to review, debug and maintain. To ensure
> that code looks familiar to all developers on the project it’s important to agree on a common set of conventions.

All headers will get anchors automatically, so there's no need to have the {#...} after each header.

src/codeConventions.md line 74:

> 73:
> 74: <div class="box">
> 75: <div class="boxheader">Motivation</div>

You can use markdown to create a div with a specific class, as used for the navigation bars for instance:
::: {.NavBit}
[« Previous](codeConventions.html) • [TOC](index.html) • [Next »](reviewBodies.html)
:::

src/codeConventions.md line 6:

> 5: :::
> 6:
> 7: This is a set of code conventions for for JDK Release Projects in the OpenJDK Community. Other OpenJDK Projects, and
> projects outside of OpenJDK, are welcome to adopt these guidelines as they see fit.

There's a lot of html in this file. I would prefer if as much as possible (all?) could be converted to markdown.

src/guidestyle.css line 10:

> 9: /***************************************/
> 10:
> 11: /* Use a section symbol as list item for style guide items */

The style of most things should be consistent through the guide, and also with the rest of the pages on
openjdk.java.net. I don't mind improving on that style, but that should be a separate change that is applied to all
pages.

src/codeConventions.md line 125:

> 124:
> 125: For questions regarding Oracle copyright or license notices, please contact <a
> href="mailto:iris.clark at oracle.com">iris.clark at oracle.com</a>. 126:

Did Iris agree to this? :-)

src/codeConventions.md line 405:

> 404: <ul class="conventions">
> 405: <li>Source code and comments should generally not exceed 80 characters per line and rarely if ever exceed 100
> characters per line, including indentation. 406: <div class="box">

Was this actually agreed to? 80 cars is a truly ancient number. Especially Java code tends to be slightly chatty and
have longer lines, especially with a few levels of indentation. I wouldn't want to have lines up to 180-200 characters,
but 120-140 is not excessive in my mind.

I'm looking at some Java code I wrote not long ago with an inline Thread - run() declaration inside an if, with a loop
and a few ifs in it... This may be exceptionally bad Java code, but it has four spaces of indentation and 9 indentation
steps in the deepest end. That's almost half of the 80 chars in just indentation. I personally don't find this code the
least difficult to read. But then again, the actual lines themselves are not more than ~100 characters long, they are
just moved to the right a bit due to indentation.  Could the 80-100 lines be excluding indentation?

-------------

Changes requested by jwilhelm (Lead).

PR: https://git.openjdk.java.net/guide/pull/14