Programming with Assertions © Allan C. Milne v

Agenda. What are assertions? Use of assertions. When not to use assertions. the Java assert statement. Examples of using assertions.

What are assertions? Tests that assumptions you make about the state of your program are in fact correct. Note that they are not about validating state that might occur (either as an error or invalid state); this should be checked in the usual programmatic manner. Assertions relate to assumptions about normal operation of your program; normal operation includes handling invalid and error conditions.

Calculate distance travelled … … from various values within the program;  assume that all values have been appropriately validated;  assume the calculation is correctly implemented. We can assert that distance travelled is >= 0.

So what? If the assertion fails then the program will fail with an appropriate assertion error: unhandled exception error message; stack trace will be displayed. this tells the developer that some of the assumptions made are incorrect; the developer must revisit their design and/or implementation.

Execution time. You might think that using assertions liberally within a program will result in slower, less efficient execution times. this is not the case as, in Java, assertions are disabled by default and have zero impact on execution time. Assertions can be enabled by invoking Java with the ‘-ea\ flag: java –ea MyProgram

Typical workflow. Developer includes assertions in their code. Enable assertions during testing. Normal operation executes the program with assertions disabled. On unexpected program results or crash: rerun with assertions enabled; debug and test with assertions enabled until repaired.

Why use assertions? No-cost for normal execution-time operation. Gives more confidence in the correctness of software. Aids in debugging unexpected faults. Self-documenting code Leads to more robust software.

Don’t use assertions for … … validation of values. … detection of error conditions. … checking parameter values in public methods. … any application-level logic.

The Java assert statement. assert boolean-expr if the boolean-expr is false then an AssertionError is thrown. assert boolean-expr : expr as above; expr is evaluated to a string and included in the error message.

use assert for. Pre- and post-conditions. Control flow invariants. class state invariants.

Pre- and post-conditions. What must be true before and/or after some processing unit: a method, but note not for checking parameters of a public method; a computation; synchronisation lock status; etc.

Examples. // compute distance travelled … distance = … assert distance>=0.0 : distance; // private helper method; we assume that // parameters are validated in the public code. private void doSomething (int units, String message) { assert (units>10) && (message!=null); … … … }

control-flow invariants. Assert the assumed condition for the last else clause in a multi-way if. Assert places in the code that you assume cannot be reached; for example the default clause in a ‘closed’ case. Use assert false; for this.

Examples. PlayingCard card; … … … switch (card.suit()) { case Suit.Hearts: … … … break; case Suit.Clubs: … … … break; case Suit.Diamonds: … … … break; case Suit.Spades: … … … break; default: assert false : card.suit(); // or alternatively use the statement: //throw new AssertionError (card.suit()); } int minutes; … … … final int quarter = minutes % 60 / 15; if (quarter == 0) { … … … } else if (quarter == 1) { … … … } else if (quarter == 2) { … … … } else { assert quarter==3; … … … }

Class state invariants. What must be true about the state of every instance of a class. Often this is the assumptions made about the relationships between the values of the fields making up the object’s state. Define in a private helper function; call the function from assert statements; include these statements at the end of all public methods.

State invariant coding pattern // constructor method. public YoHo (…) { … … … assert isConsistent(); } // … and for all public methods … public void doThis (…) { … … … assert isConsistent(); } … … … } // end YoHo class. class YoHo { // private fields defining an object state … … … … // Helper function defining consistency. private boolean isConsistent () { // perform appropriate checks on object state. … … … }

Reference links. Oracle documentation: Programming guide on using assert. Programming guide on using assert Wikipedia: Assertions in software development.