Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Ariya Hidayat

August 11, 2015
Tweet

More Decks by Ariya Hidayat

Other Decks in Programming

Transcript

  1. And How to Avoid Them

    View full-size slide

  2. [14, 3, 77]
    [14, 3] [77]

    View full-size slide

  3. 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 full-size slide

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

    View full-size slide

  5. Readable, consistent,
    crystal clear

    View full-size slide

  6. 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 full-size slide

  7. 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 full-size slide

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

    View full-size slide

  9. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  14. // 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  22. '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 full-size slide

  23. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  26. Public = Irreversible

    View full-size slide

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

    View full-size slide

  28. “Write 3 examples which
    use the API”

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide