“I am indeed amazed when I consider how weak my mind is and how prone to error.” – Rene Descartes
- 1 Introduction
- 2 A Startling Fact About Errors in Code
- 3 The Front Line in the War on Errors
- 4 Why Use Assertions
- 5 What are Assertions
- 6 How to Create A VBA Assertion
- 7 When to Use Assertions
- 8 Assertions Versus Error Handling
- 9 How to Turn Assertions On or Off
- 10 What to Avoid
- 11 Using Assertions With Collections and Objects
- 12 Summary
- 13 Major Advantages of Assertions
- 14 Get the Free eBook
This post shows a simple technique that will vastly reduce the number of errors in your VBA code. I have used this technique thousands of times on countless projects. It will save you considerable time creating applications and it will make your application practically bulletproof.
If you adopt this technique then I guarantee you will see results almost immediately. Reading about it is not enough – you have to actually try it out for yourself. Once you see how useful it is you will want to keep using it.
The simple technique I’m referring to is the Assertion statement. It is simple to use and implement and will provide dramatic results. However don’t be fooled by the simplicity of an Assertion. Used correctly it is an incredibly powerful way of detecting errors in your code.
Before we look at Assertions lets have a quick look at a startling fact about errors
A Startling Fact About Errors in Code
According to Steve McConnell in Code Complete, “there are about 15 – 50 errors per 1000 lines of delivered code”.
Just think about this for a moment. If you average the time on each bug to 30 minutes then your are talking 8 to 25 hours spent on errors for every 1000 lines of code.
30 Minutes is an optimistic average. When a bug is found in delivered code many of the following steps are required
- Reproduce the bug
- Emails about details of the issue
- Find the bug
- Fix the bug
- Update the Bug Report
- Create new version of the code
- Test the new version
- and so on
If you find a bug in development
- Find the problem and fix it
This leads us to the following rule:
Therefore finding bugs early and close to the cause is a priority. Let’s have a look at your first line of defence when it comes to errors. Then we will look at Assertions
The Front Line in the War on Errors
In VBA there are some basic tools for finding errors. These are very important for catching errors before you run your code. So it’s vital that you use them in your development. I’m going to briefly mention them here.
The Interpreter : The interpreter in VBA checks each line of code as you write it. When you press return it will check for errors in the line and display the error if it finds one. These type of errors are referred to as syntax errors.
The Compiler : Before you run your code you should always compile it to find any existing errors. To compile select Debug->Compile VBAProject from the menu.
The type of errors found by the compiler relate to more than one line. So for example, if you have an If statement without a corresponding End If statement. Other types are calling a Sub that does not exist, For without Next, Do without Loop, Select with End Select and so on.
Note: If you Run your code(Run->Run Macro from menu) it will find some of the same errors. However it will only check in the code that is being run.
Review Source Code from Mz-Tools: MZ-Tools is great tool(previously free now with 30 day free trial) that provides extra functionality to the VBA Editor that includes reviewing the source code. This review looks for items such as unused variables, parameters and other useful items.
To use this tool select Other Utilities->Review Source Code from the MZ-Tools toolbar
Now that we have covered the basic error finding methods lets look at using Assertions.
Why Use Assertions
We have just looked at ways of detecting errors in your code. However certain errors will not appear until you run it. This is where Assertions come into play.
A great description of Assertions can be found in the book Debugging Windows Programs (2000 Developmentor Series)
“You can add information to your code to have the program itself automatically detect many types of run-time errors”
The key phrase here is “automatically detect”. Once you add Assertions to your code they will automatically check for errors each time you run your code. This makes it very difficult for many types of errors to exist. So running your code with Assertions is a fantastic way of smoking out errors.
What are Assertions
Assertions are used in development to check your code as it runs. An Assertion is a statement that evaluates to true or false. If it evaluates to false then the code stops at that line. This is useful as it stops you close to the cause of the error.
Let’s explain using an analogy. Imagine the different paths through your code were the streets of a city and variables were vans that drove the streets. Assertions would then be checkpoints that ensure the vans(variables) contain valid goods(values) before they are allowed to pass.
If the city was full of checkpoints it would be very difficult for the Van to travel far with invalid goods. It’s the same with code. The more Assertions there are the harder for the code to run for long with errors.
In the city solution the checkpoints would affect performance. They would slow the city traffic considerably. With Assertions there are no performance issues. They are turned off when you deliver your software to the user. This means you can add as many Assertions as you like and it will have no affect on how your code runs.
How to Create A VBA Assertion
It is simple to create an assertion in VBA. You use the function Debug.Assert followed by a Condition.
Debug.Assert Worksheets.Count > 0 Debug.Assert Text <> ""
Here are some more examples
' This will fail if readRow is not 1 or greater Dim readRow As Long Debug.Assert readRow > 0 ' This will fail if month is not between 1 and 12 Dim month As Long Debug.Assert month >= 1 And month <= 12 ' This will fail if firstname is blank Dim FirstName As String Debug.Assert FirstName <> "" ' This will fail if the workbook is not assigned to anything Dim wk As Workbook Debug.Assert Not wk Is Nothing
When the code meets a Debug.Assert line it evaluates the condition. If the condition evaluates to false then the code stops on this line. If it evaluates to true then the code simply continues on.
When to Use Assertions
The best way to use Assertions is to test the following items:
- The input values of a Sub/Function
- A value before it is returned from a function
- A value that is received from a function
- A global variable before it is used
The following functions uses Assertions to test
- the values of the input parameters (Precondition)
- the value that is being returned(Postcondition)
Function GetType(price As Long, shipType As String) As Double ' TEST THE INPUTS(Preconditions) Debug.Assert price > 0 And price < 100 Debug.Assert Len(shipType) = 1 ' Do some calculations Dim newVal As Double If shipType = "A" Then newVal = price + 3.99 ElseIf shipType = "B" Then newVal = price + 5.99 Else newVal = price + 0 End If ' TEST THE RETURN VALUE(Postconditions) Debug.Assert newVal > 0 ' Return the value GetType = newVal End Function
In the next example, we use an Assertion to test the return value from a function
Sub RunReport() Dim total As Long total = CalculateTotal() ' check that total is in the expected range(1 to 999) Debug.Assert total>0 And total <1000 End Sub
Assertions Versus Error Handling
Error handling is used in code to anticipate error conditions and deal with them.
For example, sometimes a workbook you are trying to open my have been moved, deleted or renamed. In this case the code should report the error and return to the state before it tried to use this file.
Let’s look at a second example. Imagine you use a software application to play music files. If you try to play an invalid file the application should inform you the file is incompatible. The application should then return to it’s previous state – ready for you to select a file to play as if nothing happened. The application not stop working or begin working incorrectly.
The following code shows a simple example of error handling. We use the Dir function to check the file exists. If not then we inform the user there is a problem. We only attempt to open the file when we know it actually exists.
Sub ReadData(ByVal filename As String) ' Use Dir to check the file exists If Dir(filename) = "" Then ' Tell the user the file does not exist MsgBox "Could not find the file " + filename Else ' Open workbook Workbooks.Open filename End If End Sub
The difference between Assertions and Error Handling is that
- Assertions deal with values coming from an internal source
- Assertions are used to inform the programmer of errors and not the user
- Error Handling deals with errors coming from an external source e.g. opening files, user input, spreadsheet data etc.
Let’s update the example above so it uses both Assertions and Error Handling.
Sub ReadData(ByVal filename As String) ' USE ASSERTION TO CHECK VALUES FROM INSIDE APPLICATION Debug.Assert filename <> "" ' USE ERROR HANDLING FOR ERRORS FROM OUTSIDE APPLICATION ' Use Dir to check the file exists If Dir(filename) = "" Then ' Inform the user MsgBox "Could not find the workbook: " + filename Else ' Open workbook Workbooks.Open filename End If End Sub
If these seems confusing just remember you mostly use assertions on arguments and return values.
How to Turn Assertions On or Off
Assertions are used to check your code during development or maintenance. When you give your application to a user then you turn the Assertions off. This provides us with two really great advantages:
- You can add as many Assertions as you like as it will not have any impact on the code you give the user
- If in doubt about adding an Assertion then add it anyway. You can easily remove it and it won’t affect the user.
Let’s look at how to turn Assertions On and Off.
To turn Assertions On/Off we use a special type of If statement to surround our code. This is the #If statement – note the #character before the If . First of all we need to create a “Conditional Argument” that we can use in this if statement
Select Tool->VBAProject Properties from the VBA menu.
You can see in the screen shot that we have written Debugging = 1 in the cryptically named textbox “Conditional Compilation Arguments”. Debugging can be any name we like and =1 means it is currently true.
We use this argument to decide if we are going to use certain code when our application runs. The following code shows how to use the #If statement with the compilation argument i.e. in this case Debugging
Function GetType(price As Long, shipType As String) As Double #If Debugging Then ' Test inputs(Preconditions) Debug.Assert price > 0 And price < 100 Debug.Assert Len(shipType) = 1 #End If End Function
In the above example the assertions are only used when Debugging is turned on(set to a value other than 0). When we turn debugging off this code will not be used.
When we want to turn off the Assertions we simply change the Conditional Argument in the dialog to Debugging = 0.
This means all the code inside the #If Debugging statements will not be used.
What to Avoid
Never put executable code inside a #If statement. Only use code that will help you when debugging. In VBA this is essentially the two statement types Debug.Assert and Debug.Print.
The second statement writes to the Immediate Window(Ctrl G or View->Immediate Window from Menu) and it useful for testing code.
The following example is something you should avoid doing
#If Debugging Then ' Don't use executable inside #If statements Debug.Assert WriteData() = True #End If End Sub Function WriteData() As Boolean WriteData = False End Function
The correct way to write this code is shown in the following example
Sub TestAssert() Dim success As Boolean success = WriteData() #If Debugging Then Debug.Assert success = True #End If End Sub Function WriteData() As Boolean WriteData = False End Function
In the second example, there is no executable code in the #If statement. This is important as it means the code will run exactly the same when you turn debugging on or off.
Using Assertions With Collections and Objects
When you are using a Collection you should check two things:
- If the Collection has been created
- If the collection has elements
Lets look at how to create a collection. We can declare in one line and create in a second line like this code shows
Sub CreateCollection1() ' Declare a collection variable Dim coll As Collection ' Assign coll to a new empty collection Set coll = New Collection End Sub
We can also declare and create in one single line as the next example shows.
Sub CreateCollection2() ' Declare and create collection in one line Dim coll As New Collection End Sub
In the first example the variable Coll is set to Nothing until we use the Set command to create a new Collection for it.
So when using Collections(or any object) we need first to check they are not empty(Set to Nothing).
The following example shows how to check an object is set to something
Sub TestCollection(coll As Collection) Debug.Assert Not coll Is Nothing End Sub
This code may seem strange as it has two negatives – Not and Nothing. However all objects are tested this way so you can use it even if you don’t understand it at first.
The next example shows Assertions that test a Workbook and Worksheet object to ensure they have been assigned to something.
Sub WriteData(wk As Workbook, sh As Worksheet) Debug.Assert Not wk Is Nothing Debug.Assert Not sh Is Nothing End Sub
When using Collections it is also a good idea to check that it contains some elements
Sub TestCollection(coll As Collection) Debug.Assert Not coll Is Nothing Debug.Assert coll.Count >= 1 End Sub
The following is a summary of the main points of this post
- Finding errors early is vital
- It will save time and improve quality
- Assertions find errors during run time
- Assertions are created in VBA using Debug.Assert
- They are used during development and mantainence
- Assertions are not a substitute for error handling code
- Assertions provide information to the programmer not the user
- If in doubt add the Assertion anyway. You can easily remove it from the code.
- Assertions are turned off when the code is released. It is simple to do this in VBA.
Major Advantages of Assertions
- It is simple to add them to your code
- They automatically detect errors when your code is running
- They have no performance issues as you turn them off upon release.
Get the Free eBook
Please feel free to subscribe to my newsletter and get exclusive VBA content that you cannot find here on the blog, as well as free access to my eBook, How to Ace the 21 Most Common Questions in VBA which is full of examples you can use in your own code.