Javadoc and Style Javadoc Format Tags Types Command Style - PowerPoint PPT Presentation

Javadoc and Style Javadoc • Format • Tags • Types • Command Style Guidelines Automated Style Checker

Javadoc • javadoc is a Java utility used to produce professional documentation such as the Java API • We will use javadoc comments to – describe what a class does and give its author – describe what a method does and give information about its parameter(s) and return value , if any

Javadoc Comments • Javadoc comments start with /** and end with */ • Note that there are 2 *’s after the initial / This is what distinguishes Javadoc comments from area comments that start with /* • Javadoc comments are placed immediately before whatever they are commenting

Javadoc Tags • Javadoc tags allow us to specify the author of a class and give information about a method’s parameter(s) and return value . • The tags start with an @ sign. These are the tags we will be using: @author - Use to specify the author of a class. @param - Use a param tag for each method parameter. Give the name of the parameter followed by a description of the parameter. @return - Use one return tag for non-void methods to describe its return value • There are many other Javadoc tags that we will not be using.

“ Javadocing ” a Class /** * Calculates Body Mass Index (BMI) * @author Bob Jones */ public class BMICalculator {

“ Javadocing ” a main method /** * Repeatedly prompts the user for weight (lbs.) * and height(in.) and outputs the BMI. * @param args command line arguments (not used) */ public static void main(String[] args) {

“ Javadocing ” a method /** * Calculates Body Mass Index (BMI) * @param weight weight in pounds * @param height height in inches * @return Body Mass Index (BMI) */ public static double calculateBMI (double weight, double height) {

“ Javadocing ” a void method /** * Outputs a word a given number of times * @param word word to output * @param number number of times to output * the word */ public static void printWords(String word, int number) {

What To Do With Javadoc • Once you are finished writing Javadoc, you can create a webpage that describes what your code can do and how to use it • This way, you can give someone the webpage and not your source code • The command for this is javadoc followed by the name of the java file csc$ javadoc ClassName.java • This creates a webpage in the working directory called ClassName.html

Style Guidelines • https://pages.github.ncsu.edu/engr-csc116- staff/CSC116-Materials/course-resources/style- guidelines.html • Style – Indentation, spaces (not tabs) – Method, variable, constant naming conventions – Space before and after operators – No lines longer than 100 characters – Proper Javadoc (class, methods, constants) – No magic numbers – No TODO comments

Automated Style Checker • https://pages.github.ncsu.edu/engr-csc116- staff/CSC116-Materials/course-resources/style- guidelines-resources/automated-style-checking.html • On laptop – https://pages.github.ncsu.edu/engr-csc116- staff/CSC116-Materials/csc116-git-wiki/git-tools – Download git: • https://git-scm.com/downloads • Install git • On Windows: open Git Bash

Install and Run Style Checker • Install – cd ~ – git clone https://github.ncsu.edu/engr- csc116-staff/cs-checkstyle.git • Run – ~/cs-checkstyle/checkstyle YourFile.java

Automated Style Checker – examples • cd ~/cs-checkstyle/examples • ~/cs-checkstyle/checkstyle Fail1.java ** Doing style check... Starting audit... /Fail1.java:32: warning: 'for' child have incorrect indentation level 13, expected level should be 12. Audit done. • If all is good: ** Doing style check... Starting audit... Audit done.