API Names and Begging the Negatives

DZone 's Guide to

API Names and Begging the Negatives

Having an unambiguous, intuitive, easy to understand API is crucial for its success. Author Ariya Hidayat explores the perils of using the negative forms of names and its potential consequences.

· Integration Zone ·
Free Resource

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.


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 the 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!

api, documentation, naming

Published at DZone with permission of Ariya Hidayat , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}