Category Archives: Api Design

Permission to change parameter and return references

When you hold a reference to an object you can change its state by for example calling methods of the object which have side effects or by setting different values for fields or properties. On first sight this is very natural to OO programming but can lead to problems when others do the same with the same object. Imaging you pass a collection to a method as parameter and while the method enqueues the collection for further processing, you keep on changing it. This can lead to behavior you most likely did not intend: You wanted the method to work with the state of the collection it had when you called the method. Instead it will use the state it has at the time of processing. Ideally all parameters your method takes are immutable (like primitive / value types or string) but in reality this will not always be possible.

Do provide clear documentation for a method regarding who has permission to change the content of all referenced objects reachable by reference type parameters after the method returns.

Similar to the (in) parameters the same thoughts apply for the (out) return value.

Do provide clear documentation for a method regarding who has permission to change the content of all referenced objects reachable by the returned value.

Following example illustrates documenting parameters

/// <summary>
/// Creates new customers in database
/// </summary>
/// <param name="customers">List of new customers</param>
/// <remarks>All reference type parameters and their children
/// must not be modified after calling this method.</remarks>
public void CreateCustomersInDatabase(List<customer> customers)
// ..

In this example it becomes clear why it is important to clarify that none of the reachable objects from any reference type parameter must be changed. Even though the caller might not modify the List he still might change the state of Customer objects referenced by the List. Obviously that is also not wanted by the method.


Do always prefer using immutable data structures.


Flattr this!

Null as return value

Avoid bothering your users with null values – either as value for parameters or as a return value.  With null as return value callers will have to write if cascades to deal with the null values at some point. This makes code both hard to write and read. In most cases null means “empty”, “none”, “not available” or “not yet available” and exactly that should be expressed by other appropriate language constructs.

In the following example GetResult could return null which requires extra logic by the caller:

String result = GetResult();
if (result == null)
    result = "prefix";
    result = result.Insert(0, "prefix");
Avoid returning null.


Do provide an API comment which makes it clear what possible return values of the method are. For example: “Method never returns null”.


Generalized not returning null but something “empty” is known as the null pattern. In case a method wants to return a value which expresses “not available” and this is not considered as an error it always should return an object which implements the null pattern.


To express empty strings, collections or an enumerable use the corresponding empty string or collection. Namely: String.Empty, new List() or other empty collections and Enumerable.Empty()


Sometimes you are in the situation where it indeed plays a role whether the return value is null or empty. For example consider a dictionary of strings as keys and values and a LookUp operation on it. The caller needs to distinguish between the meanings “key not found” and “value is empty”. The latter is expressed by returning String.Empty but then this not available anymore for the “key not found” message for which it becomes tempting to returnnull.


When there is a semantic difference between null and “empty” consider introducing a helper structure (or use System.Tuple) to transmit both: A success indicator and in case of success the result value.

Flattr this!