Skip to main content

Factoring Out Common Patterns in Libraries

A well designed core library is essential for building concise, maintainable programs in any programming language. There are many common, recurrent patterns when writing code, and ideally, these recurring uses should be factored into their own abstractions that are distributed as widely as possible throughout the core library.

Consider for instance, an "encapsulated value" pattern:
/// <summary>
/// A read-only reference to a value.
/// </summary>
/// <typeparam name="T">The type of the encapsulated value.</typeparam>
public interface IValue<T>
{
/// <summary>
/// A read-only reference to a value.
/// </summary>
T Value { get; }
}

This shows up everywhere, like Nullable<T>, Lazy<T>, and Task<T> (property called "Result"), IEnumerator<T> (property called "Current"), and many many more.

However, the common interface of a value encapsulated in an object has not been factored out into a common interface in the .NET Base Class Library (BCL). This means one cannot write programs that are agnostic over the type of a value's container, resulting in unnecessary code duplication.

A legitimate argument against this approach is that the containers each have different semantics. For instance, accessing Lazy.Value will block until the value becomes available, but Nullable.Value always returns immediately.

Fortunately, this is not an argument against factoring out the "encapsulated value" pattern, but an argument for another interface that exposes these semantics. In this case, the new pattern is an "optional value":
/// <summary>
/// A volatile value.
/// </summary>
/// <typeparam name="T">The type of value held in the reference.</typeparam>
public interface IVolatile<T>
{
/// <summary>
/// Attempt to extract the value.
/// </summary>
/// <param name="value">The value contained in the reference.</param<
/// <returns>True if the value was successfully retrieved, false otherwise.</returns>
bool TryGetValue(out T value);
}
public interface IOptional<T> : IValue<T>, IVolatile<T>
{
/// <summary>
/// Returns true if a value is available.
/// </summary>
bool HasValue { get; }
}

Lazy, Nullable and Task all exhibit these exact semantics. Programs can then be written that are agnostic over how optional values are encapsulated and processed, and the common interfaces ensure the different behaviours are overloaded in a consistent, familiar way.

We can extend this even further to "mutable encapsulated values, aka, references":
/// <summary>
/// A mutable reference.
/// </summary>
/// <typeparam name="T">The type of value the reference contains.</typeparam>
public interface IRef<T> : IValue<T>
{
/// <summary>
/// The value in the reference.
/// </summary>
new T Value { get; set; }
}

This pattern is less common, but still quite prevalent. For instance, see ThreadLocal<T> (which could also implement IOptional and IVolatile incidentally).

These interfaces have been in the Sasa library for quite some time, and are used consistently throughout the entire library. The consistency has helped considerably in guiding the design of new abstractions, and clarifying their use, since developers can simply understand any new abstraction in terms of the familiar interfaces it implements.

I suppose the lesson to take from all this is to hunt down common patterns, and aggressively factor them out into reusable abstractions. This helps the library's consistency, thus helping clients learn your API by reducing the number of unnecessary new properties and methods.

Comments

Anonymous said…
Too bad we don't have typeclasses in .Net, which would enable us to factor out the similarities which BCL authors didn't.
Sandro Magi said…
Agreed! We can sort of get around it though, in a similar way to how I circumvented C#'s inability to specify Delegate, Enum, etc. as type constraints: a wrapper class and IL rewriting to erase the wrapping, and generate code for all the cases.

It's not nearly as pretty as type classes though.
Qwertie said…
At least two new languages, Go and Rust, solve the problem of "a type that you can't change doesn't explicitly implement an interface, but has all the methods of the interface". Go interfaces are sorely missed in the .NET framework, since common collection patterns like IEnumerable+Count and IEnumerable+Count+indexer have no interface; and most collection classes that were written for .NET 1.0 still don't implement any generic interfaces at all.

I made a general solution at http://www.codeproject.com/Articles/87991/Dynamic-interfaces-in-any-NET-language

... but because it's relatively heavyweight, using a dynamic assembly and all, and because I'm a performance freak, I still tend to write specialized wrappers for common cases.
Sandro Magi said…
What you're after are ad-hoc extensions. I explained how to achieve ad-hoc extensions in another post.

P.S. sorry for the double-post, chrome ad-blocker ate my first link.

Popular posts from this blog

async.h - asynchronous, stackless subroutines in C

The async/await idiom is becoming increasingly popular. The first widely used language to include it was C#, and it has now spread into JavaScript and Rust. Now C/C++ programmers don't have to feel left out, because async.h is a header-only library that brings async/await to C! Features: It's 100% portable C. It requires very little state (2 bytes). It's not dependent on an OS. It's a bit simpler to understand than protothreads because the async state is caller-saved rather than callee-saved. #include "async.h" struct async pt; struct timer timer; async example(struct async *pt) { async_begin(pt); while(1) { if(initiate_io()) { timer_start(&timer); await(io_completed() || timer_expired(&timer)); read_data(); } } async_end; } This library is basically a modified version of the idioms found in the Protothreads library by Adam Dunkels, so it's not truly ground bre

Building a Query DSL in C#

I recently built a REST API prototype where one of the endpoints accepted a string representing a filter to apply to a set of results. For instance, for entities with named properties "Foo" and "Bar", a string like "(Foo = 'some string') or (Bar > 99)" would filter out the results where either Bar is less than or equal to 99, or Foo is not "some string". This would translate pretty straightforwardly into a SQL query, but as a masochist I was set on using Google Datastore as the backend, which unfortunately has a limited filtering API : It does not support disjunctions, ie. "OR" clauses. It does not support filtering using inequalities on more than one property. It does not support a not-equal operation. So in this post, I will describe the design which achieves the following goals: A backend-agnostic querying API supporting arbitrary clauses, conjunctions ("AND"), and disjunctions ("OR"). Implemen

Easy Automatic Differentiation in C#

I've recently been researching optimization and automatic differentiation (AD) , and decided to take a crack at distilling its essence in C#. Note that automatic differentiation (AD) is different than numerical differentiation . Math.NET already provides excellent support for numerical differentiation . C# doesn't seem to have many options for automatic differentiation, consisting mainly of an F# library with an interop layer, or paid libraries . Neither of these are suitable for learning how AD works. So here's a simple C# implementation of AD that relies on only two things: C#'s operator overloading, and arrays to represent the derivatives, which I think makes it pretty easy to understand. It's not particularly efficient, but it's simple! See the "Optimizations" section at the end if you want a very efficient specialization of this technique. What is Automatic Differentiation? Simply put, automatic differentiation is a technique for calcu