Transcript 11-Error Handling and 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, 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
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: 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 Sun/Oracle’s documentation, under
Exception Summary in java.lang
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];
}
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)
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
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 < 1 or i >= number of scores
*/
public int getScore(int i)
Syntax of Javadoc Comments
package newutil;
import java.util.Collection;
public interface TrueStack<E> extends Collection<E>{
/**
* 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.
}
Running Javadoc
• Add comments to your code
• Run javadoc from the terminal, as follows:
$ javadoc –d <destination directory> <source directory>
• A doc directory appears in your cwd, and
you can browse your documentation