CodeContracts

Code Contracts: Contract.Exists() (11 of n)

Meile Zetstra — Mon, 26 Jul 2010 16:08:00 GMT

Like the Contract.ForAll, the Contract.Exists method comes in two flavors, one that takes two integers as lower and upper bound and a Predicate<int>, and a generic one that takes an IEnumerable<T> and a Predicate<T> as input. And where the Contract.ForAll method checks that any entry that is passed to the given Predicate returns true, the Contract.Exists method will return true if at least one of the entries returns true on the Predicate.

Let’s give a simple example. With the ForAll method gave an example that would test a list for having the ten prime numbers greater than a given value x. It actually omitted an additional check which is the following:

      Contract.Requires(Contract.ForAll(0, primeList.Count - 1, p => primeList[p] < primeList[p + 1]));

This checks that for all items in the list, the next value is actually greater than the preceding one. In order to do something similar with the Contract.Exists method, lets write a method that requires at least one of the given numbers is prime:

    public List<int> FindAtLeastOnePrimeFollowingX(int x, List<int> numberList)
    {
      Contract.Requires(x > 0);
      Contract.Requires(numberList != null);
      Contract.Requires(numberList.Count > 5);
      Contract.Requires(Contract.ForAll(0, numberList.Count, p => numberList[p] > x));
      Contract.Requires(Contract.ForAll(0, numberList.Count - 1, p => numberList[p] < numberList[p + 1]));
      Contract.Requires(Contract.Exists(0, numberList.Count, p => numberList[p].IsPrime()));
 
      return (from p in numberList
              where p.IsPrime()
              select p).ToList();
    }

This is just an example showing the working of the Code Contracts methods. I have no intention to bring this as a real world example. I probably will come up which such an example in a later stage. The last precondition in the example checks the requirement that there must be at least one prime number in the list passed as the second parameter. I was going to insert a post condition in here as well, which would ensure that in the result I would also have at least one prime number, but the ensures fails with the warning:

CodeContracts: ensures unproven: Contract.Exists(Contract.Result<List<int>>(), p => p.IsPrime())

Even though the predicate on the IsPrime is in the LINQ statement, the static checker is currently not able to project this also onto the post condition that I defined. Maybe this will get better in the near future.

Next post in the series will be about the Contract.Assume method, which can be used to indicate to the static checker that even though static analysis on its own isn’t able to prove certain facts, the fact is still true and should be treated as proven.

That’s it for now
Meile

Code Contracts: Contract.EnsuresOnThrow<TException>() (10 of n)

Meile Zetstra — Thu, 22 Jul 2010 10:17:00 GMT

In previous post I dabbled about the post conditions using the Contract.Ensures method. But what if the method body throws an exception? Or any called method throws? How would you ensure certain state without the Code Contracts? Probably using some try-finally construction or just a try-catch. But as with other conditions, pre and post, the try-finally and try-catch will only have impact on the current enclosing method body, and not on any derived or overridden one.

With the help of the Contract.EnsuresOnThrow<TException> this gets a little bit easier. It will ensure the post condition not only on the current enclosing method body, but also on any derived and overridden member. Let look at an example:

    public bool AddAndProcessItem(T item)
    {
      Contract.Requires(item != null);
      Contract.Ensures(this.Count == Contract.OldValue<int>(this.Count) + 1);
      Contract.EnsuresOnThrow<DbException>(!item.IsProcessed);
 
      try
      {
        // do processing here which may throw a DbException...
      }
      catch (DbException)
      {
        item.IsProcessed = false;
        throw;
      }
 
      this.innerList.Add(item);
      return true;
    }

Here the post condition ensures that on a DbExeption being thrown the item’s IsProcessed property will have the value false. The example shown here catches a possible thrown DbException, sets the state property and lets the exception propagate to a higher level. But you could also have code that throws an exception itself, for instance when a certain operation is invalid, you might throw an exception of type InvalidOperationException. If we would have the following just preceding the try-clause:

      if (this.innerList.Contains(item))
      {
        throw new InvalidOperationException("Item cannot be processed when it is already added.");
      }

we could add the following post condition:

      Contract.EnsuresOnThrow<InvalidOperationException>(item.IsProcessed == Contract.OldValue<T>(item).IsProcessed);

This would ensure that also in case of an InvalidOperationException the IsProcessed value of the item is the same as it was before entering the method. So the method body should not have ‘touched’ this property in case of the InvalidOperationException being thrown.

This concludes the parts about post conditions. In this I discussed the use of Contract.ForAll() already in this post, which is not restricted to use in post conditions, but may be used in preconditions as well. And even beyond those. There is also the Contract.Exists call, which will be the subject of the next post. After that I’ll try to post something useful on Contract.Assume and Contract.Assert. Also the object invariant is still left to discuss, with the Contract.Invariant call. And of course there are still a few attributes to dabble about.

That’s it for now
Meile

Code Contracts: Contract.ValueAtReturn<T>() (9 of n)

Meile Zetstra — Wed, 21 Jul 2010 14:00:00 GMT

This post will deal with the Contract.ValueAtReturn() method of the Microsoft Code Contracts. The method enables the contract to specify post conditions on out parameters. Where the Contract.Result is used to get a peek at the final return value, the Contract.ValueAtReturn does almost the same thing on out parameters.

To make it a bit more clear, I created a simple example:

    public bool TestingOutParameter(int x, out int y)
    {
      Contract.Ensures(!Contract.Result<bool>() ?
                       Contract.ValueAtReturn<int>(out y) == -1 :
                       Contract.ValueAtReturn(out y) == x + 1);
 
      if (x == int.MaxValue)
      {
        y = -1;
        return false;
      }
 
      y = x + 1;
      return true;
    }

This tests the incoming parameter x, when it is int.MaxValue, the method will return false and y will have the value of -1, otherwise it will return true and y will equal x + 1. Please note that in the example I have included the type int in the first call, but not in the second. It would not have been necessary to put it in either call, since the compiler would have inferred the type from the usage anyway. I included it to show that it could be used in both ways. However, if the type can not be inferred, it MUST be stated and can not be omitted.

Just like the Contract.OldValue the method can only be used in a Contract.Ensures call. And speaking of post conditions, there is just one call left to deal with in that part. And that is the Contract.EnsuresOnThrow call. And that will be the subject of the next post in this series.

That’s it for now
Meile

Code Contracts: Contract.OldValue<T>() (8 of n)

Meile Zetstra — Tue, 20 Jul 2010 10:47:00 GMT

Continuing our series on Code Contracts. This time with the Contract.OldValue<T>() method. This method will return the value of the given variable at the start of the enclosing method or property. It is however only valid to use this method in a post conditional Contract.Ensures method call.

And that immediately indicates it’s purpose. It should be used to enable the use of post conditions that depend on the state of the world at method entry, compared to that at the return. For instance, if you would have a class with some collection or list functionality, you could have an Add method. The Contract.OldValue<T>() method enables you to check the count at method exit compared to the count at method entry. The following example shows this:

    public void Add(T item)
    {
      Contract.Requires(item != null);
      Contract.Ensures(this.innerList.Count == Contract.OldValue<int>(this.innerList.Count) + 1);
 
      this.innerList.Add(item);
    }

The count at method exit should match the old count incremented with 1 for the added item. There may be other uses for the Contract.OldValue(). Just remember, it may only be used in Contract.Ensures calls, which limits the use to post conditional checking. Any other checks on pre-entry state should be handcrafted by the programmers themselves. Another way of checking object state is the use of the Contract.Invariant method calls in a private method marked with the ContractInvariantMethod attribute. A description of those will follow in some future post in this series. Next post will deal with the Contract.ValueAtReturn<T>() method call.

That’s it for now
Meile

Code Contracts: Contract.ForAll() (7 of n)

Meile Zetstra — Mon, 19 Jul 2010 16:59:00 GMT

This post in the series on Code.Contracts is all about the Contract.ForAll method. It comes in two flavors, one that iterates in a for-loop way, and a generic form that iterates over an IEnumerable of T in a more foreach kind of way.

In the example I have used so far, I included at one point the check with Contract.ForAll<char> to ensure all the characters in the result must be equal to the first character of the input string. Unfortunately the static checker of Code Contracts is unable to ensure the correctness of this for all test. It probably has got to do something with the fact that the current System.String implementation does not include the contract checks on the constructor we’re using. Hence the checker presents you with a warning like this:

CodeContracts: ensures unproven: Contract.ForAll(0, count, p => Contract.Result<string>()[p].Equals(input[0]))

I’ve tried a few things to work around this warning, but haven’t had any luck so far. So if anyone has a brilliant idea how to get rid of it, be my guest.

So I created a different example to explain the Contract.ForAll method, which will be proven nicely by the static checker. Here goes:

    public bool FirstTenPrimesFollowingX(int x, List<int> primeList)
    {
      Contract.Requires(x > 0);
      Contract.Requires(primeList != null);
      Contract.Requires(primeList.Count == 10);
      Contract.Requires(Contract.ForAll(0, primeList.Count, p => primeList[p] > x));
      Contract.Requires(Contract.ForAll<int>(primeList, p => p.IsPrime()));
 
      return (from p in primeList
              where !p.IsPrime()
              select p).Count() == 0;
    }

This example tests whether the list of primes in the second parameter will only contain the next ten primes greater than the value in the x input parameter. There is a number of preconditions present, all of them checking a bit of the contract. The first ensures the value of x is greater than 0, the second makes sure the list of primes is not null, the third ensures the count of the given list is 10. The fourth is a call to Contract.ForAll, this is the first flavor mentioned above. It iterates from 0 to the count of the primeList, and ensures each value is greater than x. The fifth and last check is using the second flavor of Contract.ForAll, which is the generic form. In this particular case, the type of int could have been inferred from the usage, but I’ve chosen to put it here explicitly to make it clear we’re calling the generic form of Contract.ForAll. It validates that each entry in the list is indeed prime.

Let me note that there is no real world purpose to the example’s method body. It simply confirms that there is no non-prime value in the list, which is already ensured by the method’s contract. As may have become clear from the example, the Contract.ForAll is not restricted to Contract.Ensures calls. It’s not even restricted to any Contract calls. However, be aware of how and when to use this.

The next post I will take the Contract.OldValue<T>() method as the subject. This is a method that is restricted to usage in post conditions. And there is still some ground to cover on the end of the post conditions, as there is also the Contract.ValueAtReturn<T>() method and the other post condition Contract.EnsuresOnThrow<TException> method as well.

That’s it for now
Meile

Code Contracts: Contract.Result<T> (6 of n)

Meile Zetstra — Mon, 19 Jul 2010 09:55:00 GMT

The previous post was about post conditions, and more specific the Contract.Ensures method. In the example I used another method on the Contract class, Contract.Result<T> to get the eventual result of the method. The Contract.Result<T> has been backed in to give the programmer a convenient way to get the result of the method beforehand.

The T defines the type of the return value, and logically it must match the return type of the enclosing method body. The return value of the Contract.Result<T>() method call is the actual return value of the enclosing method. The method can only be used in Contract.Ensures() method calls. So this is not some convenient way to get the return value beforehand at any place in your method body.

To refresh the memories a bit, here’s the example again:

    public string RepeatFirstCharacter(string input, int count)
    {
      Contract.Requires<ArgumentNullException>(input != null);
      Contract.Requires<ArgumentException>(input.Length >= 0, "The input should have at least one character.");
      Contract.Requires<ArgumentOutOfRangeException>(count > 0);
      Contract.Requires((0 + 1) <= input.Length);
      Contract.Ensures(Contract.Result<string>().Length == count);
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

The Contract.Ensures call now verifies that the return value of the enclosing method has actually got a length that is equal to the count input parameter’s value. I’ve also added another precondition, since the static code checker of Code Contracts proposed another precondition, to ensure the result can be correctly computed. It’s the following line:

      Contract.Requires((0 + 1) <= input.Length);

This ensures the result can use the ToCharArray(0, 1) code without a possible exception being thrown at you at runtime. In my last post I also referred to the Contract.ForAll<T> method. This will actually be the subject of the next post in this series.

That’s it for now
Meile

Code Contracts: Contract.Ensures (5 of n)

Meile Zetstra — Thu, 15 Jul 2010 15:44:00 GMT

This is the first post that will be about post conditions. So far, I’ve tried to shred some light on defining preconditions with the help of the Code Contracts that are now part of the .NET framework since version 4. In the past, preconditions could and would be defined with the help of the IF-THEN-THROW construction. For a broader explanation on that, see my previous post in this series.

Now I’ll move on to post conditions. I have not often included post conditions in my code. Of course you would design your code to never return a null value, of that would be a requirement. But how would you go about checking that? A possible construction would be the following:

    public int Process()
    {
      var processable = from p in this.currentList
                        where p.Processable
                        select p;
 
      int result = processable.Count();
 
      // process the bunch....
 
      if (result != processable.Count())
      {
        throw new Exception("Count does not match number of processed items");
      }
 
      return result;
    }

The code above has some points to be cautious about. For instance, the value in the variable that is returned might have been changed on a different thread, before it is returned by the method body. How would you verify that? That would not be easy, especially not when your code is not as succinct as it could be and probably has dependencies you were not even aware of. Of course the code above contains a major flaw, since it uses a LINQ query to determine the count of items. But would every developer be aware of this?

Luckily now there is the Contract.Ensures method to the rescue. As I’ve stated before, there is no ‘silver bullet’, and this one is no exception. It does not end all bugs in your code, but it goes a long way. The binary rewriter would make sure the code is checked at the end of the method. But that’s something you could implement yourself. However, the static checker goes the other mile, by checking what you’ve stated must be true. And in the above example, if it were written with the use of Contract.Ensures, the checker would warn you about the fact that the currentList’s entries may have their Processable property changed and therefore it can not verify the correctness of your post condition.

Now back to our main example targeted also in our previous posts. Rewritten with the help of the Contract.Ensures method it will become like this:

    public string RepeatFirstCharacter(string input, int count)
    {
      Contract.Requires<ArgumentNullException>(input != null);
      Contract.Requires<ArgumentException>(input.Length >= 0, "The input should have at least one character.");
      Contract.Requires<ArgumentOutOfRangeException>(count > 0);
      Contract.Ensures(Contract.Result<string>().Length == count);
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

This verifies that the length of the returned string value is equal to the int count parameter. An additional check could be the following:

      Contract.Ensures(Contract.ForAll<char>(Contract.Result<string>().ToCharArray(), p => p == input[0]));

This verifies that result only contains the first character of the string input parameter. You may have been wondering what this construction Contract.Result<> is used for. Well, that will be the topic of the next post in this series. And the Contract.ForAll<> will follow in another post as well. Just stay tuned.

That’s it for now.
Meile

Code Contracts: Contract.EndContractBlock() (4 of n)

Meile Zetstra — Tue, 13 Jul 2010 14:45:00 GMT

In this post of the series on Code Contracts, it’s all about the Contract.EndContractBlock method. This method could be seen as some magical marker to get the benefits of Code Contracts and all the checks that come with them. It is intended to be used in legacy code to mark the end of a contract block.

Given the example I used in my previous posts:

    public string RepeatFirstCharacter(string input, int count)
    {
      if (input == null)
      {
        throw new ArgumentNullException("input");
      }
 
      if (input.Length < 1)
      {
        throw new ArgumentException("The input should have at least one character.", "input");
      }
 
      if (count <= 0)
      {
        throw new ArgumentOutOfRangeException("count");
      }
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

This could very easy be rewritten with a call to the Contract.EndContractBlock() method to get the benefit of the Code Contracts. It would end up like this:

    public string RepeatFirstCharacter(string input, int count)
    {
      if (input == null)
      {
        throw new ArgumentNullException("input");
      }
 
      if (input.Length < 1)
      {
        throw new ArgumentException("The input should have at least one character.", "input");
      }
 
      if (count <= 0)
      {
        throw new ArgumentOutOfRangeException("count");
      }
 
      Contract.EndContractBlock();
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

There are some things to note here though. Not every block of argument checking etc. could be easily marked with the EndContractBlock call. Any code that precedes the call to Contract.EndContractBlock() must adhere to the following form:

if throw

There can not be an else branch in the statements. Also the code in the condition must be side-effect free, and the exception that is to be thrown must be at least as visible as the method in which the contract occurs. As mentioned already in my post on Contract.Requires, the conditions in the IF-THEN-THROW statements are the negation of the conditions that occur as part of the Contract.Requires method. This is something to be aware of when working with contracts.

The Code Contracts binary rewriter will convert the code marked by the Contract.EndContractBlock into code similar to the code that uses Contract.Requires which was explained in my previous post here. The Contract.EndContractBlock call is only needed as a marker when there are no other or further calls to the Contract’s static members. If we were to enhance the code with an additional precondition, or with a new post condition, it would make the call to Contract.EndContractBlock() obsolete.

The following example would also result in use of all benefits of Code Contracts, even though there is no explicit call to Contract.EndContractBlock():

    public string RepeatFirstCharacter(string input, int count)
    {
      if (input == null)
      {
        throw new ArgumentNullException("input");
      }
 
      if (input.Length < 1)
      {
        throw new ArgumentException("The input should have at least one character.", "input");
      }
 
      if (count <= 0)
      {
        throw new ArgumentOutOfRangeException("count");
      }
 
      Contract.Ensures(Contract.Result<string>().Length == count);
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

This example has a new post condition that has been added. The call to Contract.Ensures is a post conditional check, which is performed on the result of the method. Contract.Ensures is to be explained in the next post in this series.

That’s it for now.
Meile

Code Contracts: Contract.Requires<TException> (3 of n)

Meile Zetstra — Mon, 12 Jul 2010 21:38:00 GMT

The previous post on Code Contracts was about Contract.Requires. That method comes with an overload, which is a generic one that takes an Exception type as the generic type parameter. The purpose of this method is mainly in line with that of the Contract.Requires method that I explained in the previous post here.

The original code sample contained a few ArgumentExceptions that were thrown if certain conditions were not met. The use of the Contract.Requires method made the code more succinct with less clutter, but the exceptions were nowhere to be found. In case the precondition is not met in the code that uses Contract.Requires, a ContractException will be thrown at runtime. Sometimes it is feasible though to throw a more specific exception, like the ArgumentExceptions that were thrown in the IF-THEN-THROW constructions.

Just to step back to the code we had initially:

    public string RepeatFirstCharacter(string input, int count)
    {
      if (input == null)
      {
        throw new ArgumentNullException("input");
      }
 
      if (input.Length < 1)
      {
        throw new ArgumentException("The input should have at least one character.", "input");
      }
 
      if (count <= 0)
      {
        throw new ArgumentOutOfRangeException("count");
      }
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

This code is very specific about the exceptions. About the ArgumentOutOfRangeException one could argue that it is actually not a correct exception to throw here, since there is no specific range, but beyond that, the exceptions serve a purpose. It is up to the requirements of the final code and build whether or not the exception must be of the ArgumentException family, or it should be a more ‘general’ ContractException, since it involves the predefined contract. When it is necessary to have the existing exceptions, one should use the Contract.Requires<TException> overload. The example code would end up looking like this:

    public string RepeatFirstCharacter(string input, int count)
    {
      Contract.Requires<ArgumentNullException>(input != null);
      Contract.Requires<ArgumentException>(input.Length >= 0, "The input should have at least one character.");
      Contract.Requires<ArgumentOutOfRangeException>(count > 0);
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

Beyond the fact that the more specific exception is used on contract failure, all other points mentioned in the post on Contract.Requires, also apply to Contract.Requires<TException>. The overload has an additional caveat though. The exception type that is to be thrown must have a public constructor accepting a single string argument. If such a constructor can not be determined at runtime, an internal ContractException will be created and thrown instead.

To conclude the posts on preconditions, the next will handle about Contract.EndContractBlock(). Even though it is not specific for preconditions, it will only truly serve a purpose when it appears at the end of legacy preconditions that are stated in the form of IF-THEN-THROW.

That’s it for now.
Meile

Code Contracts: Contract.Requires (2 of n)

Meile Zetstra — Mon, 12 Jul 2010 10:28:00 GMT

This second post in the series on Code Contracts will deal with the Contract.Requires method. In the introduction, I already mentioned that the Contract.Requires method is used to express a precondition. Whenever something has to be validated upfront, the Contract.Requires method is the one to use.

In the old style programming, any precondition would be stated as an IF-THEN-THROW construction, like in the following example:

    public string RepeatFirstCharacter(string input, int count)
    {
      if (input == null)
      {
        throw new ArgumentNullException("input");
      }
 
      if (input.Length < 1)
      {
        throw new ArgumentException("The input should have at least one character.", "input");
      }
 
      if (count <= 0)
      {
        throw new ArgumentOutOfRangeException("count");
      }
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

Not only does this create a lot of clutter, it also expresses the conditions from the negative, exceptional point of view. Looking at the code, it is required for the input to be a non-null string with a length of 1 or more. But the conditional check is on a null string value, and a length smaller than 1. If we were to rewrite the code above with the use of Contract.Requires, we would end up with the following code:

    public string RepeatFirstCharacter(string input, int count)
    {
      Contract.Requires(input != null);
      Contract.Requires(input.Length >= 0);
      Contract.Requires(count > 0);
 
      return new string(input.ToCharArray(0, 1)[0], count);
    }

Now all the clutter has gone. The code is more succinct, and the conditions really reflect the contract in a non-exceptional manner. Given the fact that in many software development cycles the specifications are mainly written in terms of requirements, it’s a good thing to have this also in the code. Since the Code Contract preconditions, post conditions, object invariants etc. can all be merged into the generated XML documentation, this also means the requirements will also appear in them as well.

Moreover, the contracts as defined using the IF-THEN-THROW style will only affect the current call. If the RepeatFirstCharacter method had been defined as a virtual method, any derived class that implements an override will have to check for the contract itself. When using Code Contracts, this is no longer necessary. The binary rewriter used by Code Contracts will make sure the contract is also exposed in the derived method as well as in the base method.

All this comes with a few caveats though. Besides the fact that Contract.Requires calls must be at the beginning of the method (which is quite logical given their nature), the contract must only reference members with at least the same visibility as the enclosing method. Since the contract is exposed to clients calling the method, this requirement makes a lot of sense. Another caveat is that on a derived method additional requirements can not be set. This is one that also makes a lot of sense, since the interface definition largely determines the contract. And on an override, the interface isn’t changed, so why should the contract?

This method should be used for those preconditions that do not enforce a particular exception to be thrown, e.g. for backward compatibility reasons. In case a particular exception should be thrown one would have to use Contract.Requires<TException>(Boolean) method instead. I will dig into that method in the next post in this series.

That’s it for now.
Meile