ariya.io About Talks Articles

API Names and Begging the Negatives

2 min read

When using a programming library, it is unfortunate that we often encounter the use of function and property names in its negative variant. Particularly when there is a choice of two values, using the positive variant would help reducing confusions and ambiguities.

dragons

As a non-native speaker, understanding a request for help sometimes troubles me a little bit, especially in the first few years of using the language regularly. With English, my biggest challenge was “Do you mind if I borrow your pen?” and other similar constructs. In the beginning, almost automatically my answer was always “Yes” (of course, what I meant was “Yes, you can use my pen”). Note how my answer was semantically not in agreement with my intention. If it was expanded into “Yes, I do mind”, that definitely indicated that I did not like that person to borrow my pen.

If you wake me up in the middle of the night because you need my help to figure out whether A equals a if caseInsensitive is false, I will be having a hard time. It would have been much easier for me when that special property carries the name caseSensitive.

In the web world, it is hard to avoid this form because disabled is a popular property name, especially for form elements. This also means that the use of disabled propagates to various library, from jQuery UI to AngularJS (ngDisabled).

The same problem applies to function names. Looking at any piece of code that invokes setHidden(false), I need to pause and think to ensure that I don’t get it wrong (“is that component visible or not”). Less likely of course if it is simply setVisible(true). A similar case is to be made for methods such as disallowThis() or disallowThat(). An alternative exists, simply use the allowThis(), allowThat() variants when it makes sense.

In real-world, we are practically more familiar with the existence of thing, and not the lack of thing. You feel that the coffee shop is warm because of the heat, not due to the lack of cold. As you are ready to request a refill, your barista notices that your cup is a quarter full, not a three quarter empty.

Next time you would want to expose a property or a method in a public API, think about its positive vs negative form!

Related posts:

♡ this article? Explore more articles and follow me Twitter.

Share this on Twitter Facebook