A popular and accepted definition of craftsmanship is
Aptitude, skill, or manual dexterity in the use of tools or material. Taking time to make sure a project is done well.
The tools or materials involved in software development are whatever you need and use to build your software product well. These might include various things such as IDEs, compilers, CASE tools, frameworks, APIs, external tools, and much more. These kinds of tools and materials are things that you can buy or try, and then use them as a black box, without much knowledge on their intrinsic mechanics. You know what they’re supposed to do, so you use them in a specific context.
The aptitude, skill, or manual dexterity part of the definition is more subtle, as it can mean a lot of things to a lot of people, depending on the experience and knowledge of each individual. I believe that your attitude towards your work is also a key factor that can make a difference between delivering a good software and a better software. That attitude is what separates artists and craftsmen from the rest of the crowd. I also believe that anyone that has a will to improve their aptitude, skill, or manual dexterity to develop and deliver better software can make that leap.
This post has to do with going the extra mile (or the extra bit I should probably say…) when designing your software. I’ll take a few minutes to write about explicit interface members implementation, a useful pattern when you need for your design to respect the framework’s rules (as well as the compiler’s), without shifting your design to fully submit to those rules, which might force you to please the frameworks and tools instead of pleasing the actual user of your class in terms of code readability and testability. As you probably know, even in software development, some rules can be broken and some others can be bent. In this case, we’re going to bend them…else good luck arguing with the compiler!
According to Brad Abrams’s book “Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries“,
Explicit member implementation allows an interface member to be implemented such that it is only available when cast to the interface type.
In other words, there are two ways to access an interface member that is being explicitly implemented
- Access it by explicitly casting the object into the appropriate type holding that member.
- Access it from inside the type declaring that member.
It is a very useful concept to know and to use because it helps to design according to the specification of the type and not according to the specification of a framework or an API.
For example, suppose we have a generic collection of books, such as described in Listing 1. This class offers the possibility to add a bunch of books in a book collection, but for some reason we don’t want the user of this class to just add a single book or “multiple single books”. If a single book needs to be added, we just create a list of one book and pass that list the Add method of the class. Hey, it’s a specification! What can you do?
Listing 1.
using System.Collections.Generic;
using System.Collections;
public class BookCollection : ICollection
{
public void Add ( Book[] books )
{
// This is our own Add method.
// We want the user of this class to add a list of books to the book collection.
}
public void Add( Book item )
{
// This is the Add method from the ICollection interface that this class needs to implement.
// We're respecting the rule of the framework...and satisfying Resharper
}
// The rest of this class members will be ignored for now...
}
Now, suppose we want to use this class under Visual Studio 2005, this is what Intellisense will offer us to choose when using the Add method from our BookCollection class in Listing 2.
Listing 2.
“So which one should we use?” Actually that’s a wrong question to ask. The real question is “Which one do we need to use?” The answer is in our specification. The specification for this class states that we want to add a list a books. Therefore, we don’t want Intellisense to show, nor do we want to implicitly use, the Add method required by the ICollection interface implementation. Therefore, we should hide it. As a matter of fact, since we can’t remove it (because doing so will break the contract defined by the interface), we have no other choice but to hide it or make it private. But just because we’ll hide it, it doesn’t mean that the user can’t explicitly invoke it. Remember that rules can be broken and bent. I’ll show later how to use the hidden implementation of the method (in the name of human curiosity…)
In order to hide this member, we’ll have to explicitly implement it in our class. The mechanism provided by C# to explicitly implement a member of an interface is by declaring the method’s signature which is in the following form:
Return-value InterfaceName<GenericType>.MethodName(Parameters with their types) { // body… }
In our case, we’ll explicitly implement the Add (Book item) method in the BookCollection class, as shown in Listing 3.
Listing 3.
void ICollectionAdd( Book item )
{
throw new NotImplementedException();
}
In this case, I decided to throw a NotImplementedException() to force the user to use the other Add method if he decides to explicitly use this method. But you can do other things here, such as call another method, or write a log entry every time this method is being explicitly accessed in order to know if the design should be refactored or changed in future releases. Who knows, maybe our users do want the possibility to add just a single book. The current version of the specification doesn’t say so, but it doesn’t mean it will always be that way!
After explicitly implementing this member in our BookCollection class, Intellisense will show the following possible signature when using the Add method from our BookCollection class, as shown in Listing 4.
Listing 4.
As we can see, Intellisense now shows us the only Add method signature that we can use, therefore respecting the specification for this class. Congratulations.
If you take a look under the hood of that method with Lutz Roeder’s .NET Reflector and view the code with its IL, you’ll see that the compiler has marked the scope of the method to be private instead of public as it is shown in Listing 5.
Listing 5.
At this point, you might ask yourself “Why is the class implementing the generic ICollection interface anyways, if you want to provide your own Add method?” The answer is that I also want this class to have other collection-oriented methods, such as a Contains(), Clear() and Remove() method, and a Count property. Furthermore, I want this class to be used like a generic collection to other classes or components of my system. Therefore, implementing the provided generic ICollection interface is a good way to satisfy this requirement. Plus, I want to be able to enumerate on my elements.
There is also another method that I might not want this class to implicitly expose, and that is the IsReadOnly property. According to the MSDN documentation of the .NET Framework, A collection that is read-only does not allow the addition, removal, or modification or elements after the collection is created. Therefore, I can decide to explicitly implement this interface member in the BookCollection class as well. Going forward with that idea for the other members implemented by the BookCollection class, the class will expose only the methods, the properties, the events and the delegates with a more accurate match to my domain model, and thus publicly hiding the other “necessities” or “domain noise” required by some framework or API.
But (ah yes, that little word again…) you should be very careful when opting for this strategy. For instance, if some component uses an object of type ICollection<Book> (via dependency injection for example), and uses the IsReadOnly property before doing some other operation on the collection, it’ll call the implementation of the IsReadOnly property in the BookCollection. Therefore, if you are throwing an exception because you don’t want the user of the class to use this method implicitly, for example, it might backfire when some other component in the system will need to invoke it. You can limit the use of your class to some human users, but it’s much harder to do so when that user is a component already in operation.
Nevertheless, the user can still invoke the explicitly implemented member of an interface by casting the object to the interface holding that member, as shown in Listing 6.
Listing 6.
BookCollection bookCollection = new BookCollection();
((ICollection) bookCollection).Add( new Book() ); // Using the ICollection's Add method explicitly...
For instance, if the Add (Book item) method implements the following body,
void ICollection.Add( Book item )
{
// This is the Add method from the ICollection interface that this class needs to implement.
// We're respecting the rule of the framework...and satisfying Resharper
System.Console.WriteLine( "Using the interface member explicitly...");
}
…then we’d see the “Using the interface member explicitly…” in the console window once the method is invoked.
So when should you explicitly implement interface members?
- When you want your class to implement an interface, but prohibit the use of one service or substitute it for another service to the user.
- When a class implements two (or more) interfaces with a common set of services, such as the ones provided by the IEnumerable and IEnumerable<T> interfaces. In fact, if you implement the generic IEnumerable<T> interface, you’ll have no choice to implement the IEnumerable interface as well. You’ll have to decide which members to explicitly implement.
- When you want to hide the implementation of an interface member in your class.
That concludes this post. The main idea was to show that you should shift your design to reflect and respect the domain and its specification rather than pleasing the framework or the API. Sometimes, rules in software development can be broken, and most of the time, they can be bent, especially if it can help you to design a more consistent and concise system design. A design should speak in terms of the domain and not (or at least avoid) in the terms of the technology, framework or tool. When possible, try to abstract whatever is needed by the framework or API, but NOT required by the user of the system; the user being a human being or another system.
Related links
