Software Development Handing Errors and Creating Documentation Computer Science 209 Software Development Handing Errors and Creating Documentation

Error Handling: Who Is Responsible? The client (ultimately, the human user) The server (ultimately, the programmer of the basic software components)

Example Errors Invalid data used to create a Student object (negative numbers, etc.) The position is out of range during the retrieval or replacement of a student’s test score A stack is empty before a pop

Handling Errors, v1 A method returns true to indicate success or false to indicate failure Works well when there is only one kind of error and no other value must be returned The client checks the return value and takes action if necessary

Handling Errors, v2 A method returns null to indicate success or a string to indicate failure The string is also a message indicating the type of error (good for 2 or more types of errors) The client checks the return value and takes action if necessary

Handling Errors, v3 When Java detects an error at run time, an exception is thrown For example, when a program attempts to divide by zero, Java throws an ArithmeticException This method guarantees that errors are detected

Example: Divide by 0 int dividend = 15; int divisor = 0; System.out.println("The quotient is " + dividend / divisor); Java throws an exception and the JVM halts with an error message: A new instance of ArithmeticException is created. This object contains the error message that is displayed in the terminal window.

Example: Divide by 0 int dividend = 15; int divisor = 0; System.out.println("The quotient is " + dividend / divisor);

Example: Index Out of Bounds public int getScore(int i){ return scores[i – 1]; } An ArrayIndexOutOfBoundsException is thrown if i < 1 or i > scores.length

Throwing Your Own Exception public int getScore(int i){ if (i < 1 || i > scores.length) throw new IllegalArgumentException("i must be between " + "1 and " + scores.length); return scores[i – 1]; } Throw an exception of the appropriate type Java’s hierarchy of exception classes is listed in Oracle’s documentation, under Exception Summary in java.lang

Error Conditions Requiring Exceptions A class’s interface gives the client enough information to use a class To use a class properly, the client must be aware of possible error conditions These conditions are specified by placing preconditions and postconditions in the interface

The Interface Is a Contract Between Client and Server Preconditions - state what must be true before a method is run to produce the expected results Postconditions - state what the expected results are when the preconditions are satisfied

Guidelines for Error Handling Servers: Methods should enforce preconditions by throwing exceptions Clients: There is no need to worry about potential exceptions if you obey the preconditions first Some methods require exceptions to be caught (more on this when we examine I/O)

When You Don’t Know the Type public int getScore(int i){ if (i < 1 || i >= scores.length) throw new RuntimeException("i must be between " + "1 and " + scores.length); return scores[i – 1]; }

javadoc Java includes a tool, javadoc, and a special notation for program comments that allow you to generate Web-based documentation These comments highlight parameters, returned values, and possible exceptions for methods, as well as prefatory info on the class

Syntax of Javadoc Comments /** * text * goes * here */ Use /** to begin the comment and * at the beginning of each line.

Documenting the Class /** * A <code>Student</code> object represents a name and a set of * test scores for a student.. * @author Ken Lambert * @author Martin Osborne * @version 1.0 */ class Student extends Object implements Comparable<Student>{ // Blah blah blah } The @ symbol is a prefix for specialized comment tags

Documenting a Method /** * Returns the score at the specified position. * @param i - the position of the score * @return the score * @throws IllegalArgumentException if i less than 1 or i greater than * number of scores */ public int getScore(int i)

Running javadoc > javadoc *.java This will create Web pages for all of the classes in the current working directory There are many options as well

Packages Easy GUIs with BreezySwing For Wednesday Packages Easy GUIs with BreezySwing