The benefits of programming with assertions (a.k.a. assert statements)

by Philip Guo (philip@pgbovine.net)

Programming with assertions (a.k.a. assert statements) is a great idea ...

• because they provide run-time checks of assumptions that you would have otherwise put in code comments

  • the run-time system knows nothing about comments
  • comments often get out-of-date and out-of-sync with the code base
  • assert statements (that actually end up executing) can't get out-of-date, because if they do, then they will fail for legitimate cases and you will be forced to update them

• An assert statement simply checks a boolean condition and does nothing if it is true but terminates the program if it is false

  • e.g., assert x >= 0 for making sure the input to a square root function is non-negative
  • e.g., assert isLegalSSN(joe.getSSN()) for making sure that Joe's social security number (SSN) is legal due to some criteria defined by that function

• An assertion allows you to express in code what you assume to always be true about data at a particular point in execution ...

  • ... and terminates execution as soon as your assumption is violated
  • there's often no point in continuing execution if your assumptions no longer hold

• You probably already write comments throughout your code to document non-obvious assumptions about the values of data structures ...

  • so why don't you convert those comments into assert statements instead?
  • whenever possible, instead of (or in addition to) writing a comment, write an assert statement that expresses the same details in code

• When you are writing code filled with assert statements, you can be more confident that when execution reaches a certain point, certain conditions are guaranteed to be met.

  • This can simplify your code because after the assert statement, you can avoid other conditional checks. e.g.,:

assert (p != null);
// can now use p without first checking if it's null

• When you are debugging code filled with assert statements, failures appear earlier and closer to the locations of the errors, which make them easier to diagnose and fix.

  • The longer errors propagate before causing visible trouble, the more their form can change, and the harder they are to debug.
  • Have your program (at least during development) fail fast and early
  • An Assertion Error is the best kind of error you can hope for because you have a better chance at pinpointing its source than when you receive some other random crash.

• assert statements serve as test code integrated directly into your implementation.

  • Whenever you execute a program containing asserts, you are providing it with test cases.
  • assert statements in your implementation can complement your unit/integration testing code

• Get in the habit of writing assert statements for conditions that you think would be obviously true.

  • Bugs often appear because you didn't understand all the conditions under which a piece of code can be executed, so if you think some condition must obviously be true, then it's still very possible that in some case you haven't considered, it's actually false!

  • If you think that at a certain point in execution, x should always contain less than 15 elements, then codify it in an assert

    • e.g., assert x.length < 15
    • Just because you don't see any possible way that this condition can fail to hold doesn't mean that it's truly impossible
    • it's very difficult for humans to reason about all possible program executions except for trivial cases
    • Also, that assert statement serves as a concise replacement for a comment like "photo list x should always contain less than 15 photos."

• wah wah wah, but what about those assert statements slowing down my code?

  • in development, performance probably isn't your primary concern
    • development speed and code quality trump performance!
  • perhaps it doesn't even slow down your program by a noticeable amount!
    • most asserts are constant-time operations (e.g., simple boolean comparison or null check), with some more complicated ones being linear-time (e.g., membership tests for elements in list)
  • if you're really paranoid, surround your assert statements with an if guarded by some global DEBUG variable that you can switch off

• but don't take my word for it, even Turing Award Winner Tony Hoare also really likes programming with assertions!

Links:

• Programming with assertions in Java
• Using assertions effectively in Python
• Related concept: Design by Contract