JavaScript API Disasters

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

0284b8950e0f4a57bcc092d4dbb98d97?s=128

Ariya Hidayat

August 11, 2015
Tweet

Transcript

  1. And How to Avoid Them

  2. None
  3. None
  4. ★ Gimli

  5. None
  6. None
  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]
  9. None
  10. None
  11. https://twitter.com/AriyaHidayat/status/429111596627918848

  12. None
  13. Readable, consistent, crystal clear

  14. None
  15. None
  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
  21. None
  22. None
  23. None
  24. What’s in a name? that which we call a rose

    by any other name would smell as sweet...
  25. event.initKeyEvent("keypress", true, true, null, null, false, false, false, false, 9,

    0);
  26. // Horizontal s1 = new Slider(true); // Vertical s2 =

    new Slider(false); s1 = new Slider({ orientation: 'horizontal' }); s2 = new Slider({ orientation: 'vertical' });
  27. // Animate the resize w.resize(250, 150, true); // Do not

    animate the resize w.resize(250, 150, false); w.resize(250, 150, { animate: true });
  28. // Expand + animate treeItem.setState(true, true); // Expand + don't

    animate treeItem.setState(true, false); // Collapse + animate treeItem.setState(false, true);
  29. https://twitter.com/ID_AA_Carmack/status/367485612627984385

  30. None
  31. X.disabled = false; Y.setHidden(true); filter.caseInsensitive = true; X.enabled = true;

    Y.setVisible(false); filter.caseSensitive = false;
  32. cube.translucency = 0.2; 20% translucent cube.opacity = 0.8; 80% opaque

  33. status.message("Ready"); page.forward(); page.backward(); status.showMessage("Ready"); page.goForward(); page.goBackward();

  34. picker.yearFrom = 1980; picker.yearTo = 2020; picker.minimumYear = 1980; picker.maximumYear

    = 2020;
  35. this.callMe = "Adam"; flight.from = SFO; flight.to = JFK; this.name

    = "Adam"; flight.departure = SFO; flight.destination = JFK;
  36. '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) ""
  37. 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]
  38. var p = new Point(14, 3); p.translate(4, 4); var s

    = ' hal9000 '; s.trim();
  39. var p = new Point(14, 3); p.translate(4, 4); p.translated(4, 4);

    var s = ' hal9000 '; s.trim(); s.trimmed();
  40. None
  41. Public = Irreversible

  42. None
  43. None
  44. -- yours truly “You’d fail your first two attempts anyway.”

  45. “Write 3 examples which use the API”

  46. None
  47. None
  48. “YOU SHALL NOT PASS!” — Darth Vader

  49. None
  50. Apply static polymorphism Audit every shortcut Read aloud (and often)

  51. Some artworks are from http://openclipart.org. @ariyahidayat