C # Code Contracts userMessage Parameter
I'm using Code Contracts in C #, but I'm a little curious what I should be typing for a parameter userMessage
. I'll give you a short example.
I have the following statement 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 yourself and other software developers / developers.
I originally thought that
Contract.Assert(IsValidReferenceData(refData), "Payment Reference is not valid");
But then I thought it userMessage
was the exact opposite of a boolean condition, so I rewrote it as:
Contract.Assert(IsValidReferenceData(refData), "Payment Reference is valid");
Therefore, the message and condition are the same. However, it can confuse people when they see the exception report and then think, "Hold on, if the link is valid, why was the exception thrown?"
Finally, I might think, why not make a neutral statement that says what should be true:
Contract.Assert(IsValidReferenceData(refData), "Payment Reference must be valid");
Which of the above is the best practice? I want to get the correct messages because I plan on using assertions all over the place to prevent data breaches and I can check the runtime for that.
source to share
It's worth noting that while there is no recommendation for user messages about bad code contracts, there is an xUnit test pattern called Waiting Message Description that matches your last example. By answering the question about what should have happened in the assertion message, you accomplish both of your goals: code readability + providing a helpful, explanatory debug message.
source to share
So with the .Net code, I decided to see what they are using as a 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 the answer is: write whatever you want, this post is for quick debugging, not for your api users.
source to share
Code contracts (assertions, pre-clauses and afterwords and invariants) are designed to detect out-of-band environments that your code is not designed to handle. They should not be used as the first point of validation, and as a result, Contracts
should not touch contextualized user posts. The upstream validation in the presentation / service layers needed to identify any invalid user or client input of the service.
Considering that the message will only be displayed if the contract fails, which in theory should never happen in production code, this means the user's target audience will be YOU or another developer, so the message should be tailored to help you quickly debug it (if you need a message at all - the stack trace and line number are usually sufficient, IMO). The parameter name userMessage
is probably a bad choice.
source to share