rickardnilsson.net is a weblog and the online home of web developer and father of three, Rickard Nilsson... More
Rickard blogs about creating software solutions using ASP.NET and agile practices.
BlogEngine.NET ships with an extension that automatically highlights source code in blog posts. All that is required is that the source code block is surrounded with [code:lang][/code] tags. The extension will markup the code with CSS classes and the default theme includes a default color scheme for code elements like keywords, comments, and so forth. The extension ships with support for HTML, C#, JavaScript, T-SQL, MSH, and Visual Basic.
In forums and blogs in the BlogEngine community issues with the syntax highlighter extension has been brought up. Some of it can be found here, here, and here. Many has complained about how hard it is to use and lack of proper documentation. To get the tags to be recognized by the extension you have to format your post in a really precise manor with a leading and trailing <p></p>. Besides taking up a lot of unnecessary space when editing the post, this is why so many has complained that they can't get it to work. If the block is not correctly surrounded with the right amount of line breaks two things can happen. Either the whole code block is masked or the code is shown but the tags are rendered as part of the code block.
My own experience with this is pretty much the same and the only way to find out how it works was for me to read and step through the code. Since the extension is open source there is no hinder for improving the code base, hence I've been working to improve it to meet the community need, as well as my own. In addition to the mentioned usability issues I missed highlighting of types in C#, that is class, interface, and struct names which we are used to see in Visual Studio colored in cyan.
I'm about to present a new version of the extension which will include the following improvements:
Leave a comment on this post if you wish to be notified when the new version is available.
ICustomer customer = new Customer("kalle"); RegEx regex; ICollection<Customer> coll = new ICollection<Customer>(); Stack<Name.Space.Customer> stack = new Stack<Name.Space.Customer>(); stack.Put(customer); customer.Age = 24;
[Serializable] public class Customer : ICustomer , IComparable<ICustomer> { public Customer(string name) { this.name = name; person = new Person(name); } public int Age { get { return age; } set { age = value; } } IPerson _p = Person.CurrentUser; IPerson person; internal IPerson Person { get { return this.person; } }
private ShopingCart cart = new ShopingCart(); protected ShopingCart GetCart() { return cart; } }
Answer to Fredrik Normén on Defensive programming and Design by Contract on a routine level.
"Design by Contract is about creating a contract between the client and the supplier. The idea of the Design by Contract theory is to associate a specification with every software elements. This specification will define a contract between client and the supplier. When a supplier writes a contract with the client, it should document the obligations and benefits"
There is always a contract between a software element and its client. The question is if the contract is implicit or explicitly stated. Lets look at an example from the .NET framework:
public virtual void Add(object key, object value) Member of System.Collections.Hashtable
Summary: Adds an element with the specified key and value into the System.Collections.Hashtable. Parameters: key: The key of the element to add. value: The value of the element to add. The value can be null. Exceptions: System.ArgumentNullException: key is null. System.ArgumentException: An element with the same key already exists in the System.Collections.Hashtable. System.NotSupportedException: The System.Collections.Hashtable is read-only.-or- The System.Collections.Hashtable has a fixed size.
Summary: Adds an element with the specified key and value into the System.Collections.Hashtable.
Parameters: key: The key of the element to add. value: The value of the element to add. The value can be null.
Exceptions: System.ArgumentNullException: key is null. System.ArgumentException: An element with the same key already exists in the System.Collections.Hashtable. System.NotSupportedException: The System.Collections.Hashtable is read-only.-or- The System.Collections.Hashtable has a fixed size.
A short analysis conducts that the method's contract can be expressed like this:
Precondition: ○ true Postcondition: ○ If key is null ArgumentNullException is thrown ○ If ContainsKey(key) ArgumentException is thrown ○ Else this[key] == value ○ And Count == old Count + 1 An analysis of the contract shows that the contract can be made stronger like this:
Precondition: ○ Key != null ○ !ContainsKey(key) Postcondition: ○ this[key] == value ○ Count == old Count + 1 In the theory of contracts there is this concept of strong versus week contacts where the first is more demanding on the client than the last. Hence, the precondition is now more demanding on the client and this can be taken advantage of in the routine implementation. In the pseudo code below we can see the difference:
Week contract supplier
public virtual void Add(object key, object value) { if (key == null) { throw new ArgumentException(…); } if (ContainsKey(key)) { throw new ArgumentException(…); } this.buckets[hashcode(key)] = value; }
Strong contract supplier
public virtual void Add(object key, object value) { this.buckets[hashcode(key)] = value; }
Using the stronger contract we get a much cleaner implementation of the routine. How about the client code then? Well, take a look:
Week contract client
try { hashtable.Add(key, foo); } catch (ArgumentException ex) { // oops, we made a mistake! }
Strong contract client
if (!hashtable.ContainsKey(key) { hashtable.Add(key, foo); }
Of course, the code for the strong contract client can be used with the week contract as well. The main point is that with the strong contract no error handling should be made because then there is an error in the client code which should be corrected, not handled at runtime. The routine only promise to satisfy the post condition if and only if the pre condition is satisfied by the client. If the pre condition is not met the outcome is undefined and anything can happen from nothing at all to the system crashing. This is where frameworks that permit developers to express the contract in code comes in.
[FormallySpecified] public class Test { [Pre("i > 0")] public void DoWork(int i) { } }
public class Person : ContractN.ProgrammingByContract { [InRequired, OutRequired] public string Name { get; set; } }
public virtual int B.Foo(int x) { Check.Require(1 < x < 3); ... Check.Ensure(result < 15); return result; }
Proceeding with a solution there is no way of changing the implementation of the GregorianCalendar class to get the correct behavior so we have to go about this another way. One is to subclass the GregorianCalendar and override the GetWeekOfYear method. Another is to implement the GetWeekOfYear in a class totally separate from the .NET framework. I think that the first one is the way to go since the error that we're trying to correct is in the framework itself.
So, first we alter the help method in the test case to use our sub classed IsoCalendar (which we haven't written yet).
So, we are not in a compile state yet so lets do the simplest thing to get this running. I decided to subclass the GregorianCalendar class since what is wrong is the GetWeekOfYTear method of that class. I basically override that method like below.
We run the test a get a red bar. Fine, but now lets go ahead and implement the algorithm. However, this has been done over and over with varying elegantness. My favorite is the work of programmer and mathematician Julian Bucknall. His original implementation can be found at his blog. So, instead of returning -1 I call the GetIsoWeek method from Bucknall's implementation and take the modulus of 100 (since the result from the algorithm is of the form YYYYWW). We run the test and we get a green bar!
Now when we get a green bar there's just one more thing to add. The ISO 8601 week should only be returned when the parameters rule and firstDayOfWeek is set properly according to the documentation. In all other cases the GregorianCalendar implementation works just fine. We fix this with a guard clause at the top and we're done.
During this series we covered test coverage for the faulty implementation of weeks according to ISO 8601. We used Test-Driven Development to provide a fix using Julian Bucknall's really smart implementation. Next we should take a look at refactoring to design patterns.
According to the ISO standard, in the period 4 January - 28 December the week number is always the same as the Gregorian week and the same also apply for all Thursdays. Thus, the mentioned dates can be safely excluded in our test coverage. Though we still have an infinite number of dates to cover, we are getting there. Finally, we can limit our test coverage to a set of years that can be reasonable argued to appear in the application which we are implementing.
To simplify it the resulting dates are non Thursdays 1-3 January and 29-31 December every year from 2005 - 2015.
Using the calendar in Outlook I compile a matrix of the week numbers in the year interval. The dates that are grayed are Thursdays which should not be part of the test.
The matrix can be thought of as a set of { date, week number } pairs which can easily be implemented in code.
I create a test which iterates over the set and makes assertions that the correct week was generated by the calendar. It turns out however, that only eleven of the dates generate a wrong week number. I refactor the code to only include the weeks that are wrong. I get a red bar and I see another opportunity for refactoring, the previous two tests can be integrated with this test by just adding the date - week pair to the set. The following is the resulting test:
Now that we have a test that fails we can come up with a solution to get the test to pass.
Abstract So, now we make up another test. Looking at the calendar we see that new years eave 2001 should also belong to the first week of 2002 according to ISO 8601. We write the test much like the previous test and we get another red bar. Now its time to refactor. We need to remove the duplicated code in the two tests. First we start with extract method which results in the following method:
Now, we can refactor the tests using the new method like this:
The implementation of weeks according to ISO 8601 (used e.g. in Sweden) is faulty in .NET Framework. In particular the GregorianCalendar and CultureInfo classes are faulty when it comes to ISO 8601. So, how do we know that the implementation of ISO 8601 is faulty using TDD? We come up with a test that fails. By the ISO definition the first week is the week with the year's first Thursday in it. So, we know that e.g. 2003-12-31 is actually week number 01 of 2004 since it is a Wednesday and thus belongs to the first week. The following is a first attempt at a test: Now we get a red bar and we know that the implementation is flawed. However, this is only a single test. If we get a green bar, is the implementation correct? No, of cource not. We need to write more tests to be sure.