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
   

   View Slide

2. View Slide

3. View Slide

4. ★
   Gimli
   

   View Slide

5. View Slide

6. View Slide

7. [14, 3, 77]
   [14, 3] [77]
   

   View Slide

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]
   

   View Slide

9. View Slide

10. View Slide

11. https://twitter.com/AriyaHidayat/status/429111596627918848
    

    View Slide

12. View Slide

13. Readable, consistent,
    crystal clear
    

    View Slide

14. View Slide

15. View Slide

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';
    

    View Slide

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;
    

    View Slide

18. point.translate(14, -3)
    rect.translateBy(26, 4)
    point.translate(14, -3)
    rect.translate(26, 4)
    

    View Slide

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
    

    View Slide

20. var x = Math.sqrt(-2)
    isNaN(x) true
    x === NaN false
    isNaN('hola') true
    x == NaN false
    

    View Slide

21. View Slide

22. View Slide

23. View Slide

24. What’s in a name?
    that which we call a rose
    by any other name
    would smell as sweet...
    

    View Slide

25. →
    

    View Slide

26. event.initKeyEvent("keypress", true, true,
    null, null, false, false, false, false, 9, 0);
    

    View Slide

27. // Horizontal
    s1 = new Slider(true);
    // Vertical
    s2 = new Slider(false);
    s1 = new Slider({
    orientation: 'horizontal'
    });
    s2 = new Slider({
    orientation: 'vertical'
    });
    

    View Slide

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
    });
    

    View Slide

29. // Expand + animate
    treeItem.setState(true, true);
    // Expand + don't animate
    treeItem.setState(true, false);
    // Collapse + animate
    treeItem.setState(false, true);
    

    View Slide

30. https://twitter.com/ID_AA_Carmack/status/367485612627984385
    

    View Slide

31. View Slide

32. X.disabled = false;
    Y.setHidden(true);
    filter.caseInsensitive = true;
    X.enabled = true;
    Y.setVisible(false);
    filter.caseSensitive = false;
    

    View Slide

33. cube.translucency = 0.2;
    20% translucent
    cube.opacity = 0.8;
    80% opaque
    

    View Slide

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

    View Slide

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

    View Slide

36. this.callMe = "Adam";
    flight.from = SFO;
    flight.to = JFK;
    this.name = "Adam";
    flight.departure = SFO;
    flight.destination = JFK;
    

    View Slide

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) ""
    

    View Slide

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]
    

    View Slide

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

    View Slide

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

    View Slide

41. View Slide

42. Public = Irreversible
    

    View Slide

43. View Slide

44. View Slide

45. -- yours truly
    “You’d fail your first
    two attempts anyway.”
    

    View Slide

46. “Write 3 examples which
    use the API”
    

    View Slide

47. View Slide

48. View Slide

49. “YOU SHALL NOT PASS!”
    — Darth Vader
    

    View Slide

50. View Slide

51. Apply static polymorphism
    Audit every shortcut
    Read aloud (and often)
    

    View Slide

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

    View Slide