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

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:

"for for" -> "for"

src/codeConventions.md line 12:

> 11:
> 12: This document provides guidelines for low level coding practices such as how to indent code and how to name types
> and variables. Many of the stylistic choices are subjective and different developers may have different opinions about
> them. Keep in mind however, that having a consistent style is more important than to satisfy each individual developers
> preference. 13:

"This document" -> "This section"

src/codeConventions.md line 15:

> 14: ## Guiding Principles
> 15: The guidelines in this document strive to maximize,
> 16:

"this document" -> "this section"

src/codeConventions.md line 17:

> 16:
> 17: <ol class="spread">
> 18:     <li>Correctness</li>

Not sure if I'm looking at the latest commit here, but if I do this part should be converted to markdown as well.

src/javaStyleGuide.md line 7:

> 6:
> 7: While this document covers a lot of ground, it should be noted that no style guide can answer all questions for us,
> and developers will always need to use good judgment towards the end of producing code that is correct, readable,
> maintainable, debuggable, consistently formatted, and aesthetically pleasing. 8:

"this document" -> "this section"

src/javaStyleGuide.md line 9:

> 8:
> 9: Examples in this document are non-normative; While they intend to illustrate correct way of formatting the code,
> there may be other ways to correctly format the code. This is a general principle: There may be several ways to format
> the code, all adhering to the guidelines in this document. 10:

"this document" -> "this section" x2
"illustrate correct way" -> "illustrate the correct way" or "illustrate a correct way"

src/javaStyleGuide.md line 46:

> 45: ## Java Source Files
> 46: This section concerns ordinary `.java` files only. Rules do not necessarily apply to other source files such as
> `.jasm`, `.sh` or `.gmk`. 47:

I think these two sentences can be removed since this document now is (intended to be) part of a collection of style
guides for different languages. For instance makefiles is planned to get their own section. The section header is
enough to convey this information.

src/javaStyleGuide.md line 6:

> 5: :::
> 6:
> 7: While this document covers a lot of ground, it should be noted that no style guide can answer all questions for us,
> and developers will always need to use good judgment towards the end of producing code that is correct, readable,
> maintainable, debuggable, consistently formatted, and aesthetically pleasing.

Looking at the division I think that the following text, down to the "Overview", would be better placed in the general
style guide section that is in the other file now. The text is true for the other languages/style guides as well imho.

src/javaStyleGuide.md line 83:

> 82: - A Java source file should be structured as follows:
> 83:   1. The copyright notice
> 84:   1. Package declaration

I would prefer if we stick to #. for numbered lists. This goes throughout the file.

src/javaStyleGuide.md line 1378:

> 1377: Cleaning up code that’s unrelated to the patch may…
> 1378: - Complicate the review of the patch in which case correctness may suffer
> 1379: - Run the risk of breaking existing code

An empty line is needed between text and list.

src/javaStyleGuide.md line 96:

> 95:
> 96:   ```java
> 97:   /*

An indented backtick code block cause problems for syntax highlighting both in my editor and here in the GitHub review.
Actually it's the indentation of the end backticks that cause the problem so this could be fixed by indenting the end
``` with at most one space. However I don't think that looks very good so I suggest to use ~~~ for indented code
blocks. ``` and ~~~ renders the same result with Pandoc. This goes throughout the file.

src/javaStyleGuide.md line 101:

> 100:   or
> 101:   ```java
> 102:   /*

The Pandoc documentation says that fenced code blocks must be separated from surrounding text by blank lines. With ```
it seems to work either way, but ~~~ requires an empty line before the block. In either case the visual result in the
end is the same so I see no reason not to follow the documentation and have empty lines before and after.

src/guidestyle.css line 49:

> 48: /* Code blocks */
> 49: pre > code {
> 50:     border: 1px solid #CCCCCC;

Note that this affects code blocks in the rest of the Guide as well. This is not necessarily a bad thing, but it should
be noted.

src/javaStyleGuide.md line 1075:

> 1074: ### Javadoc
> 1075: This section only covers basic Javadoc formatting. For a complete reference refer to  [How to Write Doc
> Comments for the Javadoc Tool](http://www.oracle.com/technetwork/articles/java/index-137868.html). 1076:

Since Javadoc is slightly out of scope, and there is a complete reference for it, can we move it down to where comments
are handled and give it a less prominent placement there?

src/javaStyleGuide.md line 1366:

> 1365: - IDE/tool-specific comments should be avoided wherever possible, especially when there are reasonable
> alternatives, such as external settings files, etc. 1366: - Comments should be grammatically correct and follow general
> recommendations of technical writing. 1367: :::

The three Javadoc lines can be added at the end here and the examples below. Then have the link to the complete guide
in a "For more information..."-link.

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

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