RFR: Updated section on Code Conventions. [v4]

[Andreas Lundblad]

On Thu, 25 Jun 2020 03:42:50 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Andreas Lundblad has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Changed from 1. to #. in a few ordered lists.
>>  - Added an empty line to separate text from list.
>
> 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.

Good point. I grep'ed for `<code` and found out that this styling messed up code blocks in hgHelp and tClone. Updated
those files.

I also noted that code blocks are formatted using blockquotes here and there. Perhaps this is because there hasn't been
any proper styling for code blocks before? I think they should be turned into `~~~`, but I'll address that in a
separate change.

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

Not 100% sure I understood. Let me know what you think about the latest version.

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

Sounds good. Updated.

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

Updated.

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

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