>Consistency in APIs

>

One thing that I feel is very important when building APIs is consistency in how method parameters are ordered. Abrams and Cwalina’s Framework Design Guidelines talks about this as well.

I came across one instance of inconsistency that is a good example, I think. We’re using MSTest for unit testing on our current project and so we make extensive use of it’s "Assert" class. For most of the assertions that do a comparison between and expected and actual object, you pass the expected object first. For example:

Assert.AreEqual(Of T)(expected as T, actual as T)

or

Assert.AreSame(expected as Object, actual as Object)

And now we come to the exception.

Assert.IsInstanceOfType(value as Object, expectedType as System.Type)

When using the assertion for IsInstanceOfType, suddenly it takes the actual object in the first position. This becomes annoying because now I have to remember if I put the actual or expected object first every time I use an assertion method.

Additionally, they’ve also named the expected object parameter “value” instead of “expected”.

So, when building APIs even if you are not planning on publishing them for devs outside of your project, remember to be consistent with parameter ordering and naming. It helps with discovery and adoption of the API.

Advertisements

>Splitting PDFs

>

Today I needed to split up a PDF and went looking for a tool that would do that for me.  I came across the project named PDF Toolkit (http://www.accesspdf.com/pdftk/).

Using this tool I executed the following command and, voila, I had one PDF document for each page in my input document:

pdftk.exe input_file.pdf burst

Check the included .txt file for the full set of command-line parameters.