Using the cognitive dimensions - consistency

Consistency in an API allows users to make use of what they have learned about how one part of the API works when they start working with another, similar part of the API. One way to measure and describe how consistent your API is, is as follows :

 

For two or more similar user goals that the API supports, describe how similar the code required to accomplish these goals is.

 

In the System.IO namespace, two similar goals might be:

 

 

  1. Append text to the existing contents of a file.

  2. Overwrite existing contents of a file.

     

The code required for these two goals is as follows

 

//Append the existing contents of the file

      StreamWriter sw = new StreamWriter("C:\\test.txt", true);

      sw.WriteLine("Text to append to test.txt");

      sw.Close();

 

//Overwrite the existing contents of the file

      StreamWriter sw = new StreamWriter("C:\\test.txt", false);

      sw.WriteLine("Text to overwrite in test.txt");

      sw.Close();

 

In both cases the code is very similar. The only difference is the value of the second parameter in the StreamWriter constructor.

 

Consistency can be defined in the following terms

  • If the API uses the same design patterns and idioms when appropriate throughout the whole of the API, the API is fully consistent.
  • If the API uses the same design patterns and idioms for two or more similar user goals but does not use the same design patterns and idioms in all appropriate circumstances throughout the API, the API exposes core consistency.
  • If the API does not use the same design patterns and idioms at all when it would be appropriate to do so, the API exposes arbitrary consistency.

In general, most users like to work with an API that is fully consistent.