JavaScript API and its Design Principles

Presented at DevNexus 2014 in Atlanta, GA.

In this day and age it is pretty common to design a large-scale web
application as a collection of modular and reusable components. These
components need to have a reasonable set of APIs (application
programming interfaces) which deliver against the stipulated
engineering criteria. In addition this API set needs to retain ease of
use. The success of a module is thus reflected in the way it is being
used in other modules. This talk is intended to initiate the
discussion on finding the principles for designing a good JavaScript
API by observing the interactions between modules, particularly on the
influence of an interface on the code patterns. Some good and bad
examples found in real-world libraries will be shown, along with a
collection of language tools designed to detect and analyze those
patterns.

Transcript

1. JavaScript API
   Design Principles
   @ariyahidayat
   Feb 25, 2014
   Atlanta, GA
   

   View Slide

2. /usr/bin/whoami
   PhantomJS
   shapesecurity.com
   Esprima
   

   View Slide

3. treeItem.setState(true, false);
   

   View Slide

4. “How to Design a Good API and Why It Matters”
   Joshua Bloch
   “Qt API Design Principles”
   http://qt-project.org/wiki/API-Design-Principles
   Matthias Ettrich, Jasmin Blanchette
   

   View Slide

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

   View Slide

6. Modular Application Architecture
   Module A
   Module B
   interface
   

   View Slide

7. WHY?
   Nobody reads API documentation
   Code is written once, read many times
   

   View Slide

8. Readable, consistent,
   crystal clear
   Thank you, Captain Obvious!
   

   View Slide

9. Using static polymorphism
   to ensure consistency
   Preventing dangerous convenience
   such as Boolean trap
   Avoiding unreadable code
   due to confusing semantics
   

   View Slide

10. Static Polymorphism
    

    View Slide

11. 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';
    Progress Bar vs Slider
    

    View Slide

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

    View Slide

13. 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);
    corner
    dimension
    x1, y1, x2, y2 x, y, w, h
    

    View Slide

14. var x = NaN;
    isNaN(x) true
    x === NaN false
    https://twitter.com/AriyaHidayat/status/393034774245171200
    

    View Slide

15. Convenience & Traps
    

    View Slide

16. Romeo and Juliet: Act II. Scene II
    What’s in a name?
    that which we call a rose
    by any other name
    would smell as sweet...
    

    View Slide

17. Can We Have Some Vowels, Please?
    BrCtl →
    WebView
    

    View Slide

18. DOM Event
    event.initKeyEvent("keypress", true, true,
    null, null, false, false, false, false, 9, 0);
    

    View Slide

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

    View Slide

20. Boolean Modifier Trap
    // 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

21. Ping-pong, Anyone?
    // Expand + animate
    treeItem.setState(true, true);
    // Expand + don't animate
    treeItem.setState(true, false);
    // Collapse + animate
    treeItem.setState(false, true);
    

    View Slide

22. Ping-pong, Anyone?
    // Expand + animate
    treeItem.setState(true, true);
    // Expand + don't animate
    treeItem.setState(true, false);
    // Collapse + animate
    treeItem.setState(false, true);
    

    View Slide

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

    View Slide

24. Ambiguity Begets Insanity
    

    View Slide

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

    View Slide

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

    View Slide

27. Nonverbal Actions
    status.message("Ready");
    page.forward();
    page.backward();
    status.showMessage("Ready");
    page.goForward();
    page.goBackward();
    

    View Slide

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

    View Slide

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

    View Slide

30. String Extraction
    'devnexus2014'.substr(3, 9) "nexus2014"
    'devnexus2014'.substr(9, 3) "014"
    'devnexus2014'.substring(3, 9) "nexus2"
    'devnexus2014'.substring(9, 3) "nexus2"
    'devnexus2014'.slice(3, 9) "nexus2"
    'devnexus2014'.slice(9, 3) ""
    http://ariya.ofilabs.com/2014/02/javascript-string-substring-substr-slice.html
    

    View Slide

31. Array Extraction
    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]
    Immutable vs Mutable
    http://ariya.ofilabs.com/2014/02/javascript-array-slice-vs-splice.html
    

    View Slide

32. Verb = Action
    var p = new Point(14, 3);
    p.translate(4, 4);
    Does this change my string or
    return a fresh new string?
    var s = ' devnexus ';
    s.trim();
    

    View Slide

33. Explicit (Im)mutability
    var p = new Point(14, 3);
    p.translate(4, 4);
    p.translated(4, 4);
    var s = ' devnexus ';
    s.trim();
    s.trimmed();
    p does not change
    Returns a translated version of p
    

    View Slide

34. API Detective
    

    View Slide

35. Syntax Parser
    var answer = 42
    keyword equal sign
    identifier number
    Variable
    Declaration
    Identifier Literal
    Constant
    Tokenization →
    Tokens
    Parsing → Syntax Tree
    

    View Slide

36. {
    type: "Program",
    body: [
    {
    type: "VariableDeclaration",
    declarations: [
    {
    type: "VariableDeclarator",
    id: {
    type: "Identifier",
    name: "answer"
    },
    init: {
    type: "Literal",
    value: 42,
    raw: "42"
    }
    }
    ],
    kind: "var"
    }
    ]
    }
    Syntax Tree
    var answer = 42;
    Terms → ECMAScript 5.1 Specification
    https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API
    

    View Slide

37. Syntax Visualization
    http://esprima.org/demo/parse.html
    

    View Slide

38. Module Structure
    MyApp.create('MyApp.Person', {
    name: 'Joe Sixpack',
    age: 42,
    constructor: function(name) {},
    walk: function(steps) {}
    run: function(steps) {}
    });
    {
    objectName: 'MyApp.Person',
    functions: ['walk', 'run'],
    properties: ['name', 'age']
    }
    Metadata
    Meta-object
    

    View Slide

39. Collecting Member Expression
    foo.bar
    syntax = esprima.parse(code);
    traverse(syntax, function (node) {
    if (node.type === 'MemberExpression') {
    if (node.property) {
    console.log(node.property.name);
    }
    }
    });
    

    View Slide

40. Detecting Boolean Traps
    reload(x, y, false)
    function checkLastArgument(node) {
    var args = node['arguments'];
    if (args.length < 2) {
    return;
    }
    if (typeof args[args.length - 1].value === 'boolean') {
    report(node, 'Dangerous Boolean literal');
    }
    }
    

    View Slide

41. Blacklisting Function Names
    setDisabled(false)
    This block is left intentionally blank.
    Exercise for the brave reader!
    

    View Slide

42. What About API Usage?
    “You call this immutable function
    but you never assign its return
    value.”
    “You check the return value of this
    function 2000 times. Why don’t you
    do it this time (line = ….)?”
    

    View Slide

43. Best Practices
    

    View Slide

44. #1: Private by Default
    Public = Irreversible
    

    View Slide

45. SHStripMneumonic
    “Why is the function
    SHStripMneumonic misspelled?”
    Raymond Chen, Microsoft
    http://blogs.msdn.com/b/oldnewthing/archive/2008/05/19/8518565.aspx
    

    View Slide

46. View Slide

47. “Write 3 examples which
    use the API”
    #2: Public by Justification
    

    View Slide

48. View Slide

49. #3: Mandatory API Review
    

    View Slide

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

    View Slide

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

    View Slide

52. #4: API Tools
    Tools separate us
    

    View Slide

53. T D D B D D
    P D D
    

    View Slide

54. Final Words
    Practice the rituals:
    ● Apply static polymorphism
    ● Judge every convenient shortcut
    ● Read aloud (and often)
    Implement + tweak API tools
    

    View Slide

55. Thank You
    @ariyahidayat
    ariya.ofilabs.com/highlights
    speakerdeck.com/ariya
    Some artworks are from http://openclipart.org.
    

    View Slide