When should I use Debug.Assert()?

Question

I've been a professional software engineer for about a year now, having graduated with a CS degree. I've known about assertions for a while in C++ and C, but had no idea they existed in C# and .NET at all until recently.

Our production code contains no asserts whatsoever and my question is this...

Should I begin using Asserts in our production code? And if so, When is its use most appropriate? Would it make more sense to do

    Debug.Assert(val != null, "message");

or

    if ( val == null )
        throw new exception("message");

Swollen

The dichotomy you set up is the clue. It is not a question of either-or for exceptions and asserts, its both-and for defensive code. When to do which is what you are looking to understand. – Surprint

I once read somebody suggest that an exception or other method of crashing is appropriate for conditions where "There's no way I can sensibly recover from this", and additionally an assert is appropriate for conditions where "This should never happen, ever." But what realistic circumstances satisfy the latter conditions without also satisfying the former? Coming from a Python background where asserts stay on in production, I've never understood the Java/C# approach of turning off some of your validation in production. The only case for it I can really see is if the validation is expensive. – Karelia

Related: When should assertions stay in production code? – Ensign

Personally I use exceptions for public methods and assertions for private methods. – Carline

Answer 1

In Debugging Microsoft .NET 2.0 Applications John Robbins has a big section on assertions. His main points are:

1. Assert liberally. You can never have too many assertions.
2. Assertions don't replace exceptions. Exceptions cover the things your code demands; assertions cover the things it assumes.
3. A well-written assertion can tell you not just what happened and where (like an exception), but why.
4. An exception message can often be cryptic, requiring you to work backwards through the code to recreate the context that caused the error. An assertion can preserve the program's state at the time the error occurred.
5. Assertions double as documentation, telling other developers what implied assumptions your code depends on.
6. The dialog that appears when an assertion fails lets you attach a debugger to the process, so you can poke around the stack as if you had put a breakpoint there.

PS: If you liked Code Complete, I recommend following it up with this book. I bought it to learn about using WinDBG and dump files, but the first half is packed with tips to help avoid bugs in the first place.

Grannias

+1 for the concise and helpful summary. Very directly applicable. The main thing that's missing for me, though, is when to use Trace.Assert vs. Trace.Assert. I.e. something about when you do/don't want them in your production code. – Vacuity

JonCoombs is "Trace.Assert vs. Trace.Assert" a typo? – Buller

@Buller Perhaps Jon meant Debug.Assert vs. Trace.Assert. The latter is executed in a Release build as well as a Debug build. – Ensign

Answer 2

Put Debug.Assert() everywhere in the code where you want have sanity checks to ensure invariants. When you compile a Release build (i.e., no DEBUG compiler constant), the calls to Debug.Assert() will be removed so they won't affect performance.

You should still throw exceptions before calling Debug.Assert(). The assert just makes sure that everything is as expected while you're still developing.

Acidulate

Could you clarify why put in an assertion if you still throw an exception before calling it? Or did I misunderstand your answer? – Endoenzyme

@romkyns You still must include them because if you don't, when you build your project in Release mode, all validations/error-checking will be gone. – Mechanics

@Oscar I thought that was the whole point of using assertions in the first place... OK then, so you put the exceptions before them - then why put the assertions after? – Endoenzyme

Point #2 in Rory MacLeod's answer is just about needing both assertions AND exceptions – Treble

@superjos: I have to disagree: Point #2 in MacLeod's answer states that you indeed need assertion AND exceptions, but not in the same place. It's useless to throw a NullRefEx on a variable and right after do an Assert on it (the assert method will never show a dialogBox in this case, which is the whole point of assert). What MacLeod means is that in someplaces you 'll need an exception, in others an Assert will be enough. – Larcenous

It may become messy to interpret my interpretation of someone else's answer :) Anyway I with you on these: you need both of them, and you should not put the exception before the assert. I am not sure about the meaning of "not in the same place". Again, refusing to interpret, I'll just state my thoughts/preferences: put one or more asserts to check preconditions before some operation begins, or to check postconditions after the operation. Besides the asserts, and after them anyway, check if something goes wrong and needs to throw exceptions. – Treble

Use Trace.Debug() for assertions to be kept in production code, which I think is appropriate - otherwise one is releasing an untested version of the code. In particular, consider that even assert statements can have side effects! – Sufi

Answer 3

FWIW ... I find that my public methods tend to use the if () { throw; } pattern to ensure that the method is being called correctly. My private methods tend to use Debug.Assert().

The idea is that with my private methods, I'm the one under control, so if I start calling one of my own private methods with parameters that are incorrect, then I've broken my own assumption somewhere--I should have never gotten into that state. In production, these private asserts should ideally be unnecessary work since I am supposed to be keeping my internal state valid and consistent. Contrast with parameters given to public methods, which could be called by anyone at runtime: I still need to enforce parameter constraints there by throwing exceptions.

Additionally, my private methods can still throw exceptions if something doesn't work at runtime (network error, data access error, bad data retrieved from a third party service, etc.). My asserts are just there to make sure that I haven't broken my own internal assumptions about the state of the object.

Sholes

This is a very clear description of a good practice and it gives a very reasonable answer to the question asked. – Surprint

" In production, these private asserts should ideally be unnecessary work since I am supposed to be keeping my internal state valid and consistent. " The entire point is that code is imperfect and bugs will happen. Considering this, assertions should remain in the code always. – Sufi

Answer 4

From Code Complete (Wikipedia):

8 Defensive Programming

8.2 Assertions

An assertion is code that’s used during development—usually a routine or macro—that allows a program to check itself as it runs. When an assertion is true, that means everything is operating as expected. When it’s false, that means it has detected an unexpected error in the code. For example, if the system assumes that a customer-information file will never have more than 50,000 records, the program might contain an assertion that the number of records is lessthan or equal to 50,000. As long as the number of records is less than or equal to 50,000, the assertion will be silent. If it encounters more than 50,000 records, however, it will loudly “assert” that there is an error in the program.

Assertions are especially useful in large, complicated programs and in high reliability programs. They enable programmers to more quickly flush out mismatched interface assumptions, errors that creep in when code is modified, and so on.

An assertion usually takes two arguments: a boolean expression that describes the assumption that’s supposed to be true and a message to display if it isn’t.

(…)

Normally, you don’t want users to see assertion messages in production code; assertions are primarily for use during development and maintenance. Assertions are normally compiled into the code at development time and compiled out of the code for production. During development, assertions flush out contradictory assumptions, unexpected conditions, bad values passed to routines, and so on. During production, they are compiled out of the code so that the assertions don’t degrade system performance.

Wormeaten

So, what happens if a customer-information file encountered in production contains more than 50,000 records? If the assertion is compiled out of production code and this situation is not otherwise handled, doesn't this spell trouble? – Ensign

@Ensign Yes indeed. But as soon as production signals a problem and some developer (that may not know this code well) debugs the problem, the assertion will fail and the developer will immediately know that the system isn't used as intended. – Sung

Link in answer is dead - "This site can’t be reached | cc2e.com took too long to respond." – Retrogression

So users should see code in unexpected states in production rather than an error they can report and that can be properly investigated? – Sufi

Answer 5

Use asserts to check developer assumptions and exceptions to check environmental assumptions.

Hardandfast

This is the correct line of thought - additionally, time spent writing custom error messages is only valuable if someone other than a developer will have to interface with them. – Sufi

Answer 6

If I were you I would do:

Debug.Assert(val != null);
if ( val == null )
    throw new exception();

Or to avoid repeated condition check

if ( val == null )
{
    Debug.Assert(false,"breakpoint if val== null");
    throw new exception();
}

Shiftless

How is this solving the problem? With this the debug.assert becomes pointless. – Jointress

No it doesn't - it breaks into code at the point just before the exception is thrown. If you have a try / catch somewhere else in your code, you may not even notice the exception! – Shiftless

+1 I have had a lot of problems where people would simply try/catch exceptions without doing anything so tracking bug was a problem – Loriloria

I suppose there are cases where you might want to do this, but you should never catch a general exception! – Spoonful

@MarkIngram -1 to your answer, and +1 to your comment justifying it. This is a nice trick for certain peculiar circumstances, but it seems like a bizarre thing to do in general for all validation. – Karelia

I think this is one of the best answers to the question. I posted an answer which does basically the same thing but with shorter syntax, and with the ability to ignore. – Mile

Answer 7

If you want Asserts in your production code (i.e. Release builds), you can use Trace.Assert instead of Debug.Assert.

This of course adds overhead to your production executable.

Also if your application is running in user-interface mode, the Assertion dialog will be displayed by default, which may be a bit disconcerting for your users.

You can override this behaviour by removing the DefaultTraceListener: look at the documentation for Trace.Listeners in MSDN.

In summary,

• Use Debug.Assert liberally to help catch bugs in Debug builds.

• If you use Trace.Assert in user-interface mode, you probably want to remove the DefaultTraceListener to avoid disconcerting users.

• If the condition you're testing is something your app can't handle, you're probably better off throwing an exception, to ensure execution doesn't continue. Be aware that a user can choose to ignore an assertion.

Beckford

+1 for pointing out the crucial distinction between Debug.Assert and Trace.Assert, since the OP specifically asked about production code. – Vacuity

Answer 8

Asserts are used to catch programmer (your) error, not user error. They should be used only when there is no chance a user could cause the assert to fire. If you're writing an API, for example, asserts should not be used to check that an argument is not null in any method an API user could call. But it could be used in a private method not exposed as part of your API to assert that YOUR code never passes a null argument when it isn't supposed to.

I usually favour exceptions over asserts when I'm not sure.

Unloose

Answer 9

In Short

Asserts are used for guards and for checking Design by Contract constraints, i.e. to ensure that the state of your code, objects, variables and parameters is operating within the boundaries and limits of your intended design.

• Asserts should be for Debug and non-Production builds only. Asserts are typically ignored by the compiler in Release builds.
• Asserts can check for bugs / unexpected conditions which ARE in the control of your system
• Asserts are NOT a mechanism for first-line validation of user input or business rules
• Asserts should not be used to detect unexpected environmental conditions (which are outside the control of the code) e.g. out of memory, network failure, database failure, etc. Although rare, these conditions are to be expected (and your app code cannot fix issues like hardware failure or resource exhaustion). Typically, exceptions will be thrown - your application can then either take corrective action (e.g. retry a database or network operation, attempt to free up cached memory), or abort gracefully if the exception cannot be handled.
• A failed Assertion should be fatal to your system - i.e. unlike an exception, do not try and catch or handle failed Asserts - your code is operating in unexpected territory. Stack Traces and crash dumps can be used to determine what went wrong.

Assertions have enormous benefit:

• To assist in finding missing validation of user inputs, or upstream bugs in higher level code.
• Asserts in the code base clearly convey the assumptions made in the code to the reader
• Assert will be checked at runtime in Debug builds.
• Once code has been exhaustively tested, rebuilding the code as Release will remove the performance overhead of verifying the assumption (but with the benefit that a later Debug build will always revert the checks, if needed).

... More Detail

Debug.Assert expresses a condition which has been assumed about state by the remainder of the code block within the control of the program. This can include the state of the provided parameters, state of members of a class instance, or that the return from a method call is in its contracted / designed range. Typically, asserts should crash the thread / process / program with all necessary info (Stack Trace, Crash Dump, etc), as they indicate the presence of a bug or unconsidered condition which has not been designed for (i.e. do not try and catch or handle assertion failures), with one possible exception of when an assertion itself could cause more damage than the bug (e.g. Air Traffic Controllers wouldn't want a YSOD when an aircraft goes submarine, although it is moot whether a debug build should be deployed to production ...)

When should you use Asserts?

• At any point in a system, or library API, or service where the inputs to a function or state of a class are assumed valid (e.g. when validation has already been done on user input in the presentation tier of a system, the business and data tier classes typically assume that null checks, range checks, string length checks etc on input have been already done).
• Common Assert checks include where an invalid assumption would result in a null object dereference, a zero divisor, numerical or date arithmetic overflow, and general out of band / not designed for behaviour (e.g. if a 32 bit int was used to model a human's age, it would be prudent to Assert that the age is actually between 0 and 125 or so - values of -100 and 10^10 were not designed for).

.Net Code Contracts
In the .Net Stack, Code Contracts can be used in addition to, or as an alternative to using Debug.Assert. Code Contracts can further formalize state checking, and can assist in detecting violations of assumptions at ~compile time (or shortly thereafter, if run as a background check in an IDE).

Design by Contract (DBC) checks available include:

• Contract.Requires - Contracted Preconditions
• Contract.Ensures - Contracted PostConditions
• Invariant - Expresses an assumption about the state of an object at all points in its lifespan.
• Contract.Assumes - pacifies the static checker when a call to non-Contract decorated methods is made.

Profuse

Unfortunately, Code Contracts are all but dead since MS has stopped developing it. – Pudency

I can't help but find it humorous that the answer starting with "In Short" is a contender for the longest answer presented to the question. (to be fair, it reminds me of my own tendency to stay in verbose mode.) – Jacquesjacquet

Answer 10

Mostly never in my book. In the vast majority of occasions if you want to check if everything is sane then throw if it isn't.

What I dislike is the fact that it makes a debug build functionally different to a release build. If a debug assert fails but the functionality works in release then how does that make any sense? It's even better when the asserter has long left the company and no-one knows that part of the code. Then you have to kill some of your time exploring the issue to see if it is really a problem or not. If it is a problem then why isn't the person throwing in the first place?

To me this suggests by using Debug.Asserts you're deferring the problem to someone else, deal with the problem yourself. If something is supposed to be the case and it isn't then throw.

I guess there are possibly performance critical scenarios where you want to optimise away your asserts and they're useful there, however I am yet to encounter such a scenario.

Jointress

You answer deserves some merit though as you highlight some often raised concern regarding them, the fact they interrupt debugging session and the chance for false positive. However you are missing some subtleties and are writing "optimize away asserts" - which can only be based on thinking that throwing an exception and doing debug.assert is the same. It is not, they serve different purposes and characteristics, as you can see in some of the upvoted answers. Dw – Surprint

+1 for "What I dislike is the fact that it makes a debug build functionally different to a release build. If a debug assert fails but the functionality works in release then how does that make any sense?" In .NET, System.Diagnostics.Trace.Assert() executes in a Release build as well as a Debug build. – Ensign

Answer 11

According to the IDesign Standard, you should

Assert every assumption. On average, every fifth line is an assertion.

using System.Diagnostics;

object GetObject()
{...}

object someObject = GetObject();
Debug.Assert(someObject != null);

As a disclaimer I should mention I have not found it practical to implement this IRL. But this is their standard.

Freemason

Looks like Juval Lowy likes to quote himself. – Freemason

Link in answer is dead - "500 Internal Server Error". – Retrogression

@Retrogression idesign.net/Downloads/GetDownload/2100 – Freemason

Answer 12

All asserts should be code that could be optimised to:

Debug.Assert(true);

Because it's checking something that you have already assumed is true. E.g.:

public static void ConsumeEnumeration<T>(this IEnumerable<T> source)
{
  if(source != null)
    using(var en = source.GetEnumerator())
      RunThroughEnumerator(en);
}
public static T GetFirstAndConsume<T>(this IEnumerable<T> source)
{
  if(source == null)
    throw new ArgumentNullException("source");
  using(var en = source.GetEnumerator())
  {
    if(!en.MoveNext())
      throw new InvalidOperationException("Empty sequence");
    T ret = en.Current;
    RunThroughEnumerator(en);
    return ret;
  }
}
private static void RunThroughEnumerator<T>(IEnumerator<T> en)
{
  Debug.Assert(en != null);
  while(en.MoveNext());
}

In the above, there are three different approaches to null parameters. The first accepts it as allowable (it just does nothing). The second throws an exception for the calling code to handle (or not, resulting in an error message). The third assumes it can't possibly happen, and asserts that it is so.

In the first case, there's no problem.

In the second case, there's a problem with the calling code - it shouldn't have called GetFirstAndConsume with null, so it gets an exception back.

In the third case, there's a problem with this code, because it should already have been checked that en != null before it was ever called, so that it isn't true is a bug. Or in other words, it should be code that could theoretically be optimised to Debug.Assert(true), sicne en != null should always be true!

Jo

So, in the third case, what happens if en == null in production? Are you possibly saying that en == null can never happen in production (since the program has been thoroughly debugged)? If so, then Debug.Assert(en != null) at the very least serves as an alternative to a comment. Of course, if future changes are made, it also continues to have value for detecting a possible regression. – Ensign

@DavidRR, I am indeed asserting that it can never be null, and so is the assertion in the code, hence the name. I could of course be wrong, or be made wrong by a change, and that's the value of the assert call. – Jo

Calls to Debug.Assert() are removed in a Release build. So, if you are wrong, in the third case, you won't know it in production (assuming the use of a Release build in production). However, the behavior of the first and second cases is identical in Debug and Release builds. – Ensign

@DavidRR, which makes it appropriate only when I hold that it can't happen, as again it's an assertion of fact, not a check on state. Of course it's also pointless if have the assertion, have a bug it would catch, and yet never hit that case in testing. – Jo

Answer 13

Use assertions only in cases where you want the check removed for release builds. Remember, your assertions will not fire if you don't compile in debug mode.

Given your check-for-null example, if this is in an internal-only API, I might use an assertion. If it's in a public API, I would definitely use the explicit check and throw.

Boracic

In .NET, one can use System.Diagnostics.Trace.Assert() to execute an assertion in a release (production) build. – Ensign

Code Analysis rule CA1062: Validate arguments of public methods requires checking an argument for null when: "An externally visible method dereferences one of its reference arguments without verifying whether that argument is null ." In such a situation, the method or property should throw ArgumentNullException. – Ensign

Answer 14

Quote Taken from The Pragmatic Programmer: From Journeyman to Master

Leave Assertions Turned On

There is a common misunderstanding about assertions, promulgated by the people who write compilers and language environments. It goes something like this:

Assertions add some overhead to code. Because they check for things that should never happen, they'll get triggered only by a bug in the code. Once the code has been tested and shipped, they are no longer needed, and should be turned off to make the code run faster. Assertions are a debugging facility.

There are two patently wrong assumptions here. First, they assume that testing finds all the bugs. In reality, for any complex program you are unlikely to test even a miniscule percentage of the permutations your code will be put through (see Ruthless Testing).

Second, the optimists are forgetting that your program runs in a dangerous world. During testing, rats probably won't gnaw through a communications cable, someone playing a game won't exhaust memory, and log files won't fill the hard drive. These things might happen when your program runs in a production environment. Your first line of defense is checking for any possible error, and your second is using assertions to try to detect those you've missed.

Turning off assertions when you deliver a program to production is like crossing a high wire without a net because you once made it across in practice. There's dramatic value, but it's hard to get life insurance.

Even if you do have performance issues, turn off only those assertions that really hit you.

Mucoviscidosis

Answer 15

I thought I would add four more cases, where Debug.Assert can be the right choice.

1) Something I have not seen mentioned here is the additional conceptual coverage Asserts can provide during automated testing. As a simple example:

When some higher-level caller is modified by an author who believes they have expanded the scope of the code to handle additional scenarios, ideally (!) they will write unit tests to cover this new condition. It may then be that the fully integrated code appears to work fine.

However, actually a subtle flaw has been introduced, but not detected in test results. The callee has become non-deterministic in this case, and only happens to provide the expected result. Or perhaps it has yielded a rounding error that was unnoticed. Or caused an error that was offset equally elsewhere. Or granted not only the access requested but additional privileges that should not be granted. Etc.

At this point, the Debug.Assert() statements contained in the callee coupled with the new case (or edge case) driven in by unit tests can provide invaluable notification during test that the original author's assumptions have been invalidated, and the code should not be released without additional review. Asserts with unit tests are the perfect partners.

2) Additionally, some tests are simple to write, but high-cost and unnecessary given the initial assumptions. For example:

If an object can only be accessed from a certain secured entry point, should an additional query be made to a network rights database from every object method to ensure the caller has permissions? Surely not. Perhaps the ideal solution includes caching or some other expansion of features, but the design does not require it. A Debug.Assert() will immediately show when the object has been attached to an insecure entry point.

3) Next, in some cases your product may have no helpful diagnostic interaction for all or part of its operations when deployed in release mode. For example:

Suppose it is an embedded real-time device. Throwing exceptions and restarting when it encounters a malformed packet is counter-productive. Instead the device may benefit from best-effort operation, even to the point of rendering noise in its output. It also may not have a human interface, logging device, or even be physically accessible by human at all when deployed in release mode, and awareness of errors is best provided by assessing the same output. In this case, liberal Assertions and thorough pre-release testing are more valuable than exceptions.

4) Lastly, some tests are unneccessary only because the callee is perceived as extremely reliable. In most cases, the more reusable code is, the more effort has been put into making it reliable. Therefore it is common to Exception for unexpected parameters from callers, but Assert for unexpected results from callees. For example:

If a core String.Find operation states it will return a -1 when the search criteria is not found, you may be able to safely perform one operation rather than three. However, if it actually returned -2, you may have no reasonable course of action. It would be unhelpful to replace the simpler calculation with one that tests separately for a -1 value, and unreasonable in most release environments to litter your code with tests ensuring core libraries are operating as expected. In this case Asserts are ideal.

Nonferrous

Answer 16

You should always use the second approach (throwing exceptions).

Also if you're in production (and have a release-build), it's better to throw an exception (and let the app crash in the worst-case) than working with invalid values and maybe destroy your customer's data (which may cost thousand of dollars).

Tracheostomy

Nah, same as some other answers here: you dont really understand the difference so you opt out on one of the offerings, setting up a false dichotomy between them in the process. Dw – Surprint

This is the only right answer on this list IMO. Don't dismiss it so easily Casper. Debug Assert is an anti-pattern. If its invariant at debug time its invariant at runtime. Allowing your app to continue with a broken invariant leaves you in a non-deterministic state and potentially worse problems than crashing. IMO it's better to have the same code in both builds which fail fast with broken contracts and then implement robust error handling at the top level. e.g. Isolate components and implement an ability to restart them (like a tab crashing in a browser doesn't crash the whole browser). – Phylloxera

It might be helpful to include Trace.Assert in your discussion here, as it cannot be dismissed by the same argument. – Vacuity

Answer 17

I've read the answers here and I thought I should add an important distinction. There are two very different ways in which asserts are used. One is as a temporary developer shortcut for "This shouldn't really happen so if it does let me know so I can decide what to do", sort of like a conditional breakpoint, for cases in which your program is able to continue. The other, is a as a way to put assumptions about valid program states in your code.

In the first case, the assertions don't even need to be in the final code. You should use Debug.Assert during development and you can remove them if/when no longer needed. If you want to leave them or if you forget to remove them no problem, since they won't have any consequence in Release compilations.

But in the second case, the assertions are part of the code. They, well, assert, that your assumptions are true, and also document them. In that case, you really want to leave them in the code. If the program is in an invalid state it should not be allowed to continue. If you couldn't afford the performance hit you wouldn't be using C#. On one hand it might be useful to be able to attach a debugger if it happens. On the other, you don't want the stack trace popping up on your users and perhaps more important you don't want them to be able to ignore it. Besides, if it's in a service it will always be ignored. Therefore in production the correct behavior would be to throw an Exception, and use the normal exception handling of your program, which might show the user a nice message and log the details.

Trace.Assert has the perfect way to achieve this. It won't be removed in production, and can be configured with different listeners using app.config. So for development the default handler is fine, and for production you can create a simple TraceListener like below which throws an exception and activate it in the production config file.

using System.Diagnostics;

public class ExceptionTraceListener : DefaultTraceListener
{
    [DebuggerStepThrough]
    public override void Fail(string message, string detailMessage)
    {
        throw new AssertException(message);
    }
}

public class AssertException : Exception
{
    public AssertException(string message) : base(message) { }
}

And in the production config file:

<system.diagnostics>
  <trace>
    <listeners>
      <remove name="Default"/>
      <add name="ExceptionListener" type="Namespace.ExceptionTraceListener,AssemblyName"/>
    </listeners>
  </trace>
 </system.diagnostics>

Mile

Answer 18

You should use Debug.Assert to test for logical errors in your programs. The complier can only inform you of syntax errors. So you should definetely use Assert statements to test for logical errors. Like say testing a program that sells cars that only BMWs that are blue should get a 15% discount. The complier could tell you nothing about if your program is logically correct in performing this but an assert statement could.

Munro

sorry but exceptions do all the same things, so this answer doesn't address the real question. – Endoenzyme

Answer 19

I don't know how it is in C# and .NET, but in C will assert() only work if compiled with -DDEBUG - the enduser will never see an assert() if it's compiled without. It's for developer only. I use it really often, it's sometimes easier to track bugs.

Adlib

Answer 20

I would not use them in production code. Throw exceptions, catch and log.

Also need to be careful in asp.net, as an assert can show up on the console and freeze the request(s).

Sikora