Documentation
It is important both to easily grasp the design choice and the code structure of a project even long after it has been completed. The documentation process starts by commenting the code. Code comments are usually intended for software developers and aim at clarifying the code by giving details of how it works. They are usually performed using inline or multiple lines comments using the language syntax.
Single Line Comments
As we’ve seen before, we can add single-line or inline comments to our Java programs using two forward slashes // before a line in our source file:
Multiple Line Comments
Java also includes the ability to add a comment that spans multiple lines, without requiring each line to be prefixed with forward slashes. Instead, we can use a forward slash followed by an asterisk /* to start a comment, and then an asterisk followed by a forward slash to end it */, as shown below:
Documentation
Finally, Java also includes a secondary type of comment that spans multiple lines, specifically for creating documentation. Instead of a single asterisk, we use a double asterisk after the forward slash at the beginning /**, but the ending is the same as before */.
In addition, these comments typically include an asterisk at the beginning of each line, aligned with the first asterisk of the start of the comment. Thankfully, most code editors will do this for us automatically, including Codio!
These comments are specifically designed to provide information about classes and methods in our code. Here’s a quick example, using the IntTuple class developed earlier in this module:
Once we’ve written this documentation in our code, Java includes a special tool called Javadoc that will generate HTML files that describe what our code does. In fact, the Java API files, such as the one for Scanner , are generated using this tool!
For more information about writing comments for the Javadoc tool, as well as some great examples, consult the documentation .