RFR: Updated section on Code Conventions.

[Andreas Lundblad]

On Mon, 1 Jun 2020 00:26:23 GMT, Jesper Wilhelmsson <jwilhelm 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
>
> 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.

Good point. Updated according to your suggestion.

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

Nice. They have now been removed.

> 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)
> :::

Nice. Updated.

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

Managed to remove all HTML thanks to your suggestion on using the `:::` syntax.

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

I did my best to reduce it to a minimum in the last commit. Also introduced the `.conventions` class to limit the
applicability.

Unfortunately parts of the style guide is barely readable without some styling. (Consecutive code blocks doesn't look
like separate code blocks for example.) Happy to improve further if you have suggestions.

> 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? :-)

Should be removed if Iris objects obviously, but someone suggested adding this when the draft was discussed back in
2015.

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

I think most people agree with you on this (including me). Questions like these however tend to be a bit contentious so
we opted to just let the [existing
conventions](https://www.oracle.com/java/technologies/javase/codeconventions-indentation.html#313) carry over here.
This is probably something that's worth starting a separate discussion about, but I suggest we do that in a separate
change.

Does this sound good to you?

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

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