Correct use Java "assert" keyword

Question

I have never understood what is assert used for, even though I have read plenty examples, they don't really let me know what or why should I use it for.

So Instead of asking an example, I'm gonna provide one and let me know if this is the proper usage of assert.

// The idea is that the `mode` variable should be 0 or 1, and no other number.
switch(mode) {
     case 0: 
          // do stuff
          break;
     case 1:
          // do other stuff
          break;

     default:
          // assert code?
}

If this is correct, please let me know how to use it in this case. If this is not how it is supposed to use, please provide an example.

Answer 1

Not in this case.

If you're asserting a value, you're making a statement that, before some critical evaluation is done using this value, that it is what you assert it to be. You can assert that the value isn't null, or that it's less than 2, or something before you reach your critical code block.

assert (mode >= 0 && mode < 2);  // Ensures that `mode` is between 0 and 1.
// Switch statement to follow

I would not encourage the use of that here. Your code would not read well, and unless you enable assertions with the -ea flag, your assertion would not work.

Instead, what you can do is throw an exception of some kind - if it's not 0 or 1, then the mode is an illegal value which cannot be processed, leading to exceptional/undefined behavior. Throw an exception of some kind.

switch(mode) {
    case 0: 
        // do stuff
        break;
    case 1:
        // do other stuff
        break;
    default:
      throw new IllegalArgumentException("Mode is illegal");
}

Answer 2

assert object != null;
object.doSomething();

assert is used to verify the correctness of some precondition, invariant, or postcondition. In the example, we want to make sure object is not null when some method is called on it.

One thing to remember is that assert should never be executed in production code. We only make use of it when testing. There is a Java option to turn it on or off.

As for your specific example, you could use:

assert mode == 0;
assert mode == 1;

at the very beginning of the switch block to make sure only 0 and 1 are passed in.

P.S. The discussion on when to use assertion vs exception might help your understanding. The idea is that

Exceptions address the robustness of your application while assertions address the correctness of your application.