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 Freewhen 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!
Published at DZone with permission of Ariya Hidayat, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.
Comments