JavaScript API Disasters

Presented at SF JavaScript Meetup, Aug 11, 2015.

Are you confused by JavaScript’s String functions substring vs substr vs slice? How about Array’s slice vs splice? Do you realize that double-negatives, such caseInsensitive, are hard on non-native speakers? Aren’t you mad by the tedious DOM API such as initKeyEvent("keypress", true, true,null, null, false, false, false, false, 9, 0)? Why do you think one NaN will never equal to another NaN?

In this talk, we will learn from a (long) list of API bad practices found in real-world libraries and applications. Furthermore, to avoid being inducted to this API Hall of Shame, we will formulate and use the following strategies:

* Ensure consistent naming via static polymorphism
* Avoid dangerous and unnecessary shortcuts
* Mitigate confusing semantics with a proper choice of words

Transcript

1. And How to Avoid Them
4. ★ Gimli
7. [14, 3, 77] [14, 3] [77]
8. var date = [14, 3, 77] var year = a.slice(2, 1) year [] date [14, 3, 77] var date = [14, 3, 77] var year = a.splice(2, 1) year [77] date [14, 3]
11. https://twitter.com/AriyaHidayat/status/429111596627918848
13. Readable, consistent, crystal clear
16. X1.value = 'Rare'; X2.value = 'Medium'; X3.value = 'Well done'; Y.option = 'Fries'; Z.caption = 'Order'; X1.value = 'Rare'; X2.value = 'Medium'; X3.value = 'Well done'; Y.value = 'Fries'; Z.value = 'Order';
17. slider.maxValue = 100; slider.minValue = 0; slider.value = 34; indicator.range = [100, 0]; indicator.progress = 61; slider.maximum = 100; slider.minimum = 0; slider.value = 34; indicator.maximum = 100; indicator.minimum = 0; indicator.value = 61;
18. point.translate(14, -3) rect.translateBy(26, 4) point.translate(14, -3) rect.translate(26, 4)
19. corner = new Point(10, 10); dim = new Size(70, 50); R = new Rect(corner, dim); Q = new Rect(10, 10, 80, 60); corner = new Point(10, 10); dim = new Size(70, 50); R = new Rect(corner, dim); Q = new Rect(10, 10, 70, 50); x1, y1, x2, y2 x, y, w, h
20. var x = Math.sqrt(-2) isNaN(x) true x === NaN false isNaN('hola') true x == NaN false
24. What’s in a name? that which we call a rose by any other name would smell as sweet...
25. →
26. event.initKeyEvent("keypress", true, true, null, null, false, false, false, false, 9, 0);
27. // Horizontal s1 = new Slider(true); // Vertical s2 = new Slider(false); s1 = new Slider({ orientation: 'horizontal' }); s2 = new Slider({ orientation: 'vertical' });
28. // Animate the resize w.resize(250, 150, true); // Do not animate the resize w.resize(250, 150, false); w.resize(250, 150, { animate: true });
29. // Expand + animate treeItem.setState(true, true); // Expand + don't animate treeItem.setState(true, false); // Collapse + animate treeItem.setState(false, true);
30. https://twitter.com/ID_AA_Carmack/status/367485612627984385
32. X.disabled = false; Y.setHidden(true); filter.caseInsensitive = true; X.enabled = true; Y.setVisible(false); filter.caseSensitive = false;
33. cube.translucency = 0.2; 20% translucent cube.opacity = 0.8; 80% opaque
34. status.message("Ready"); page.forward(); page.backward(); status.showMessage("Ready"); page.goForward(); page.goBackward();
35. picker.yearFrom = 1980; picker.yearTo = 2020; picker.minimumYear = 1980; picker.maximumYear = 2020;
36. this.callMe = "Adam"; flight.from = SFO; flight.to = JFK; this.name = "Adam"; flight.departure = SFO; flight.destination = JFK;
37. 'sfjs-meetup'.substr(5, 6) "meetup" 'sfjs-meetup'.substr(6, 5) "eetup" 'sfjs-meetup'.substring(5, 6) "m" 'sfjs-meetup'.substring(6, 5) "m" 'sfjs-meetup'.slice(5, 6) "m" 'sfjs-meetup'.slice(6, 5) ""
38. var a = [14, 3, 77] var b = a.slice(1, 2) a [14, 3, 77] b [3] var a = [14, 3, 77] var b = a.splice(1, 2) a [14] b [3, 77]
39. var p = new Point(14, 3); p.translate(4, 4); var s = ' hal9000 '; s.trim();
40. var p = new Point(14, 3); p.translate(4, 4); p.translated(4, 4); var s = ' hal9000 '; s.trim(); s.trimmed();
42. Public = Irreversible
45. -- yours truly “You’d fail your first two attempts anyway.”
46. “Write 3 examples which use the API”
49. “YOU SHALL NOT PASS!” — Darth Vader
51. Apply static polymorphism Audit every shortcut Read aloud (and often)
52. Some artworks are from http://openclipart.org. @ariyahidayat