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
• f 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.