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.
Join the DZone community and get the full member experience.Join For Free
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
, i will be having a hard time. it would have been much easier for me when that special property carries the name
in the web world, it is hard to avoid this form because
is a popular property name, especially for
. this also means that the use of disabled propagates to various library, from
to angularjs (
the same problem applies to function names. looking at any piece of code that invokes
, 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
. a similar case is to be made for methods such as
. an alternative exists, simply use the
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!
Published at DZone with permission of Ariya Hidayat, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.