C# Code Contracts userMessage Parameter

Question

I am using Code Contracts in C# but I am a bit curious what I should be typing in for the userMessage parameter. I will give a short example.

I have the following assertion in my code:

Contract.Assert(IsValidReferenceData(refData));

This message will never be displayed to the user, but it would be nice to have an English message description in the exception for myself and other developers/maintainers of the software.

Initially I thought

Contract.Assert(IsValidReferenceData(refData), "Payment Reference is not valid");

But then I thought that the userMessage is complete opposite to the boolean condition, so I rewrote it as:

Contract.Assert(IsValidReferenceData(refData), "Payment Reference is valid");

Therefore the message and the condition are the same. However that would confuse people when they see the exception report and then think, "hang on, if the reference is valid, then why was an exception thrown?".

Lastly, I could thought, why not make a neutral statement, which says what must be true:

Contract.Assert(IsValidReferenceData(refData), "Payment Reference must be valid");

Which of the above is the best practice? I want to get to get the messages right because I plan to use assertions all over the place, to prevent irregularities in the data, and for that I am enabling run-time checking.

Answer 1

So, having .Net code I decided to look what do they use as parameter, this is the result:

"hashcode >= 0"
"Race condition detected in usages of Hashtable - multiple threads appear to be writing to a Hashtable instance simultaneously!  Don't do that - use Hashtable.Synchronized."
"Invalid MaxPrimeArrayLength"
"Missing case in GetRandomizedEqualityComparer!"
"We increment our current index by 8, so our buffer size must be a multiple of 8"
"key shouldn't be null!"
"Size is not zero"
"Didn't set Console::_out or _error appropriately!"
"Setting the foreground color before we've read the default foreground color!"

Much more here: http://pastebin.com/zPgU1ALe

Basically answer is: write whatever you want, this message is intended for you to debug quickly, not so much for your api users.