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

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

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

4. 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

5. 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

6. 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

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

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

9. Throwing Your Own Exception public int getScore(int i){ if (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 Sun/Oracle’s documentation, under Exception Summary in java.lang

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

11. 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

12. 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

13. 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)

14. Javadoc Java includes a tool, javadoc, and a special notation for program comments that allow Web-based documentation to be generated These comments highlight parameters, returned values, and possible exceptions for methods

15. Syntax of Javadoc Comments /** * text * goes * here */ /** * Returns the score at the specified position. * @param i - the position of the score * @returns the score * @throws IllegalArgumentException if i = number of scores */ public int getScore(int i)

16. Syntax of Javadoc Comments package newutil; import java.util.Collection; public interface TrueStack extends Collection { /** * Returns the element at the top of the stack. * Precondition: the stack is not empty. * @returns the top element * @throws IllegalStateException if the stack is empty. */ public E peek(); // etc. }

17. Running Javadoc Add comments to your code Run javadoc from the terminal, as follows: A doc directory appears in your cwd, and you can browse your documentation $ javadoc –d