Formatting Java documentation using Markdown best practices - Java Tutorial

- [Instructor] I'm super excited about this, but we probably don't want to start to include crazy README-like files in a markdown. So, a few best practices to mention for Java comments. First of all, please keep it simple. Stick to the basics. Use headings, lists, code blocks and emphasis, but don't go in deep headings. Usually, only Level 1 and Level 2 headings are rendered nicely. Do use those headings for structure though. Use one hashtag for the class description or title, and use the double hashtag for the method descriptions, usage examples, and sections like parameters and returns. Avoid using the old Java doc style for code blocks and ditch the <pre> and {@code} from now on. Triple backticks is the way to go for Java code with syntax highlighting, but you can still combine the markdown text with Java doc text like @param, @return, and @throws. This is actually very good, because this is telling the Java doc tooling how to parse these tags, and they generate structured documentation tables, parameters, listings, return-type info, and cross links. The markdown headings and lists are great for readability inside comments, but they don't provide machine-readable metadata, so you want to make sure to combine them to help the machine help you. And one last tip, don't make the lines too lengthy. Stick to the same line length as you code, which is typically 80 to 100 characters per line.