Java Documentation and Style

Documentation / Comments Expectations

Comments

• Comments in code that describe non-obvious code.

• Cite any resources used such as web sites, classmates, etc.

Javadoc Comments

Write Javadoc style comments for all classes and methods including:

• Description

  • A required component of every doc.

  • The first sentence (end in a period). It should be a summary sentence, concise but complete.

  • Optionally, include an additional <p> tag and a longer description.

• Block tags:

  • At a minimum, include the following:

    • For a class

      • @author - your name

    • For a method

      • @param - a description of the parameter variable, if there is one

      • @return - a description of the returned value, if the method returns something

• More comprehensive information: How to Write Doc Comments

Sample doc comments in a class

/**

* Represents a student enrolled in the school.

* A student can be enrolled in many courses.

* @author Your Name

*/

public class Student {

/**

* The first and last name of this student.

*/

private String name;

/**

* Gets the first and last name of this Student.

* @return this Student's name.

*/

public String getName() {

return name;

}

/**

* Changes the name of this Student.

* This may involve a lengthy legal process.

* @param newName This Student's new name.

* Should include both first

* and last name.

*/

public void setName(String newName) {

name = newName;

}

}

Javadoc

1. Tools -> Generate Javadoc

   1. Box to Include JDK should be unchecked

   2. Box for @author should be checked

   3. Output directory should be a docs folder in your project at the same level as the src folder.

   4. If you get an error, check that the Project SDK is set in Settings | Project Structure

2. Include generated external Javadoc in repository.

   1. Make sure to include the docs folder when you commit and push.

   2. Set the docs folder to use GitHub Pages in the repository Settings. (repo must be public)

   3. Add a link to index.html file in your Readme.

Diagrams

Add as images in README

• Class Diagrams

  • From the IntelliJ plugin (or StarUML)

  • IntelliJ: Right click package folder -> Diagrams -> Show Diagram -> Java Class Diagrams

  • If you don't have a package, add one by right clicking the src folder and choosing New -> Package then drag your .java files into it, leaving option boxes unchecked.

  • If you don't see Diagrams...

    • The plugin is available on Ultimate edition only.

    • It is installed by default but if you don't have it you can add it through File -> Settings -> Plugins -> search UML Support.

  • Only include your classes in the diagram.

  • Save the diagram as an image.

• Database Diagram

  • Right click database in Database tab -> Diagrams -> Show Visualization

  • Only include your database tables in the diagram.

  • Save the diagram as an image.