Java coding standard: problematic use of ordered lists

[PierceAndy]

codingStandards/CodingStandard-Java.md uses ordered lists for sub-sub-headings.

The way it is used is problematic because each time a section is added or removed, all subsequent numberings for the ordered list have to be individually and manually updated, i.e. they are not being recognized as proper ordered lists in markdown.

The solution would be to properly format the markdown such that the ordered lists are recognized and automatically updated, e.g. by indenting the content of each list element.

In well-formatted markdown, the following does not need manual updating

1. Heading
    text text
1. Heading
    text text
1. Heading
    text text

and would be rendered as

1. Heading
   text text
2. Heading
   text text
3. Heading
   text text

[damithc]

To be consistent with the other coding standard .md files, I would recommend using unordered lists instead. Furthermore, ordering doesn't matter here.

Note that in a document such as a coding standard where there are many items listed, we need a way to refer to a specific items from outside. e.g. refer to rule 12.

[PierceAndy]

@damithc, noted, updated issue.

In which case, should the other coding standards not already doing so (namely HTML and CSS), be updated to use numbered lists as well?

[damithc]

In which case, should the other coding standards not already doing so (namely HTML and CSS), be updated to use numbered lists as well?

Yes, we need to decide a uniform format for coding standards. We'll probably have to revisit this issue to decide on a uniform format after we have implemented support for asciidoc because it's possible that we decide to move coding standards docs to asciidoc. I'm also waiting for the semester to be over before doing any major changes to the java coding standard.