Unwanted Surprises

When that joke of an API is on you

Dear KV,

A recent small project at work required me to use JavaScript, and I was surprised to find the following note in the documentation for a code that sets a timeout:

Also note that if the value isn't a number, implicit type coercion is silently done on the value to convert it to a number—which can lead to unexpected and surprising results; see Non-number delay values are silently coerced into numbers for an example.

It's commonly accepted that languages like JavaScript and others will do duck typing, where a type is implied, but this seems to have gone a bit further, coercing any input into a number. My code doesn't allow user input to go into the timeout routine, so I'm not totally freaking out, but that bit of doc gave me pause. I just can't imagine a good reason to do what that does.

Coerced

Dear Coerced,

At least they tell you the results can be surprising, and everyone likes surprises, don't they?

Like you, KV is at a loss to understand how this type of coercion is anything like duck typing.? Just to be sure, I went to find the documentation you mentioned, and what caught my eye was this:

The time, in milliseconds, that the timer should wait before the specified function or code is executed. If this parameter is omitted, a value of 0 is used, meaning execute "immediately," or more accurately, during the next event cycle.

Now, we know that the argument expected is a time, in milliseconds, and I don't know about you, but I've never seen such a time expressed as anything but an integer number—you know, like 42. Why would anyone supply anything but a number?

It also turns out that JavaScript passes a lot of strings around, or so one might think from reading this hilarious documentation. It turns out that the string "1000" is the same as the number 1,000, which is a helpful bit of coercion, but the string "1 second" gets converted to 0, because well, just because.

It seems to me, and perhaps to you as well, that there really ought to be an error flagged at this point. If you want a number and you get a string, then say so, rather than just "trying to do the right thing," especially if the results of getting it wrong can be surprising. KV does not like surprises, and really hates them in his code.

An extra funny part of this API is, as you point out, what might happen if it took user input. Imagine a banking website that let you tell it how long you wanted to wait for a call back from an agent, and it had this joke of an API behind an input box. How many people would write "1 second" or "1 minute," or some other value that was going to be coerced to 0?

There is the higher-order question of whether loosely typed languages with coercion are really a good idea in the first place. If you don't know what you're operating on, or what the expected output range might be, then maybe you ought not to be operating on that data in the first place. But now these languages have gotten into the wild and we'll never be able to hunt them down and kill them soon enough for my liking, or for the greater good.

The only recourse we have now is to put our own protections around such APIs and make sure we know what we're passing through, before we wind up on the wrong side of a coercion.

George V. Neville-Neil works on networking and operating-system code for fun and profit. He also teaches courses on various subjects related to programming. His areas of interest are computer security, operating systems, networking, time protocols, and the care and feeding of large codebases. He is the author of The Kollected Kode Vicious and co-author with Marshall Kirk McKusick and Robert N. M. Watson of The Design and Implementation of the FreeBSD Operating System. For nearly 20 years, he has been the columnist better known as Kode Vicious. Since 2014, he has been an industrial visitor at the University of Cambridge, where he is involved in several projects relating to computer security. He earned his bachelor's degree in computer science at Northeastern University in Boston, Massachusetts, and is a member of ACM, the Usenix Association, and IEEE. His software not only runs on Earth, but also has been deployed as part of VxWorks in NASA's missions to Mars. He is an avid bicyclist and traveler who currently lives in New York City.

Originally published in Queue vol. 22, no. 4—
Comment on this article in the ACM Digital Library

More related articles:

Catherine Hayes, David Malone - Questioning the Criteria for Evaluating Non-cryptographic Hash Functions
Although cryptographic and non-cryptographic hash functions are everywhere, there seems to be a gap in how they are designed. Lots of criteria exist for cryptographic hashes motivated by various security requirements, but on the non-cryptographic side there is a certain amount of folklore that, despite the long history of hash functions, has not been fully explored. While targeting a uniform distribution makes a lot of sense for real-world datasets, it can be a challenge when confronted by a dataset with particular patterns.

Nicole Forsgren, Eirini Kalliamvakou, Abi Noda, Michaela Greiler, Brian Houck, Margaret-Anne Storey - DevEx in Action
DevEx (developer experience) is garnering increased attention at many software organizations as leaders seek to optimize software delivery amid the backdrop of fiscal tightening and transformational technologies such as AI. Intuitively, there is acceptance among technical leaders that good developer experience enables more effective software delivery and developer happiness. Yet, at many organizations, proposed initiatives and investments to improve DevEx struggle to get buy-in as business stakeholders question the value proposition of improvements.

João Varajão, António Trigo, Miguel Almeida - Low-code Development Productivity
This article aims to provide new insights on the subject by presenting the results of laboratory experiments carried out with code-based, low-code, and extreme low-code technologies to study differences in productivity. Low-code technologies have clearly shown higher levels of productivity, providing strong arguments for low-code to dominate the software development mainstream in the short/medium term. The article reports the procedure and protocols, results, limitations, and opportunities for future research.

Ivar Jacobson, Alistair Cockburn - Use Cases are Essential
While the software industry is a fast-paced and exciting world in which new tools, technologies, and techniques are constantly being developed to serve business and society, it is also forgetful. In its haste for fast-forward motion, it is subject to the whims of fashion and can forget or ignore proven solutions to some of the eternal problems that it faces. Use cases, first introduced in 1986 and popularized later, are one of those proven solutions.