Designing JS APis

Designing JS APis

The Good, The Bad, and the Ugly

212b8b6589f7e98dae14e6517101f427?s=128

Caio Gondim

May 17, 2014
Tweet

Transcript

  1. DESIGNING JS APIs THE GOOD, THE BAD AND THE UGLY

  2. GLOBO.COM

  3. GLOBO.COM

  4. BOOKING.COM

  5. LOOP INFINITO

  6. COLETANEA FRONT-END

  7. DESIGN WHY

  8. DEFINITION purpose, planning, or intention that exists or is thought

    to exist behind an action, fact, or material object DESIGN WHY
  9. APIs ARE DEVELOPERS UX DESIGN WHY

  10. CODE IS WRITTEN ONCE, READ MANY TIMES DESIGN WHY

  11. NOBODY READS API DOCs DESIGN WHY

  12. BAD THE GOOD THE UGLY THE

  13. BAD THE

  14. BAD THE IMMUTABLE vs MUTABLE var foo = [3, 5,

    8]; var bar = foo.slice(1, 2); console.log(foo); //=> [3, 5, 8] console.log(bar); //=> [5] http://ariya.ofilabs.com/2014/02/javascript-array-slice-vs-splice.html
  15. BAD THE IMMUTABLE vs MUTABLE var foo = [3, 5,

    8]; var bar = foo.splice(1, 2); console.log(foo); //=> [3] console.log(bar); //=> [5, 8] http://ariya.ofilabs.com/2014/02/javascript-array-slice-vs-splice.html
  16. BAD THE IMMUTABLE vs MUTABLE var foo = [3, 5,

    8]; var bar = foo.sliced(1, 2); console.log(foo); //=> [3, 5, 8] console.log(bar); //=> [5] http://ariya.ofilabs.com/2014/02/javascript-array-slice-vs-splice.html
  17. BAD THE IMMUTABLE vs MUTABLE var foo = [3, 5,

    8]; foo.slice(1, 2); console.log(foo); //=> [3] http://ariya.ofilabs.com/2014/02/javascript-array-slice-vs-splice.html
  18. BAD THE DOUBLE NEGATIVE foo.disabled = false; bar.setHidden(false); kung.invisible =

    false;
  19. BAD THE DOUBLE NEGATIVE foo.enabled = false; bar.setVisible(false); kung.visible =

    false;
  20. BAD THE BOOLEAN TRAP var opacitySlider = new Slider(true); var

    volumeSlider = new Slider(false); http://ariya.ofilabs.com/2011/08/hall-of-api-shame-boolean-trap.html
  21. BAD THE BOOLEAN TRAP var opacitySlider = new Slider({ horizontal:

    true }); var opacitySlider = new Slider({ horizontal: false }); http://ariya.ofilabs.com/2011/08/hall-of-api-shame-boolean-trap.html
  22. BAD THE BOOLEAN TRAP var opacitySlider = new SliderHorizontal(); var

    opacitySlider = new SliderVertical(); http://ariya.ofilabs.com/2011/08/hall-of-api-shame-boolean-trap.html
  23. BAD THE INCONSISTENCE // inconsistence button.caption = “Lorem”; radioButton1.value =

    “Easy”; radioButton2.value = “Medium”; radioButton3.value = “Hard”; checkbox1.option = “Ipsum”; checkbox2.option = “Dolor”;
  24. BAD THE GOOD THE UGLY THE

  25. GOOD THE

  26. GOOD THE STATIC POLYMORPHISM POLYMORPSHISM IS WHEN MULTIPLE IMPLEMENTATIONS CAN

    RESPOND TO THE SAME MESSAGE WITHOUT THE SENDER NEEDING TO KNOW ABOUT THE IMPLEMENTATION
  27. GOOD THE STATIC POLYMORPHISM // inconsistence button.caption = “Lorem”; radioButton1.value

    = “Easy”; radioButton2.value = “Medium”; radioButton3.value = “Hard”; checkbox1.option = “Ipsum”; checkbox2.option = “Dolor”;
  28. GOOD THE STATIC POLYMORPHISM // static polymorphism // similar classes,

    same API button.value = “Lorem”; radioButton1.value = “Easy”; radioButton2.value = “Medium”; radioButton3.value = “Hard”; checkbox1.value = “Ipsum”; checkbox2.value = “Dolor”;
  29. GOOD THE NAMING BOOLEAN PROPs // getters of boolean props

    should // start with *has*, *can* or *is* if (foo.isChecked()) { // ... }
  30. GOOD THE NAMING BOOLEAN PROPs // getters of boolean props

    should // start with *has*, *can* or *is* if (foo.hasChildren()) { // ... }
  31. GOOD THE NAMING BOOLEAN PROPs // getters of boolean props

    should // start with *has*, *can* or *is* if (foo.canBeClosed()) { // ... }
  32. GOOD THE SPECIALIZED METHODS var car = new Vehicle(110, 2014,

    true, false); var plane = new Vehicle(900, 2003, true, true);
  33. GOOD THE SPECIALIZED METHODS var car = new Car(110, 2014);

    var plane = new Vehicle(900, 2003);
  34. GOOD THE var car = new Car({ speedMax: 110, fabricationYear:

    2014 }); var plane = new Plane({ speedMax: 900, fabricationYear: 2003 }); SPECIALIZED METHODS
  35. VERBAL ACTIONS status.message(“Lorem Ipsum”); page.forward(); page.backward(); GOOD THE

  36. VERBAL ACTIONS status.showMessage(“Lorem Ipsum”); page.goForward(); page.goBackward(); GOOD THE

  37. BAD THE GOOD THE UGLY THE

  38. UGLY THE

  39. UGLY THE var letters = [“a”, “b”, “c”]; $.each(letters, function(index,

    val) {}); $.map(letters, function(val, index) {}); $(“li”).map(function(index, val) {}); Secrets of Awesome JS API Design — https://www.youtube.com/watch?v=QlQm786MClE INCONSISTENCE
  40. UGLY THE jQuery(selector [, context]) // Select jQuery(element) // Wrap

    jQuery(object) // Wrap jQuery() // Empty $ object jQuery(elementArray) // Wrap jQuery(jQuery object) // Clone jQuery(html [, ownerDocument]) // Create element jQuery(html, props) // Create element jQuery(callback) // Bind DOM loaded function Secrets of Awesome JS API Design — https://www.youtube.com/watch?v=QlQm786MClE NOT SPECIALIZED
  41. UGLY THE var evento = “Front in Fortaleza”; evento.substring(6, 8);

    // => "In" evento.substring(8, 6); // => "In" http://ariya.ofilabs.com/2014/02/javascript-string-substring-substr-slice.html INCONSISTENCE
  42. UGLY THE http://ariya.ofilabs.com/2014/02/javascript-string-substring-substr-slice.html var evento = “Front in Fortaleza”; evento.substr(6,

    8); // => "in Forta" evento.substr(8, 6); // => " Forta" INCONSISTENCE
  43. var evento = “Front in Fortaleza”; evento.slice(6, 8); // =>

    "in" evento.slice(8, 6); // => "" http://ariya.ofilabs.com/2014/02/javascript-string-substring-substr-slice.html UGLY THE INCONSISTENCE
  44. UGLY THE http://bugs.jquery.com/ticket/13103 JQUERY BOOLEAN TRAP $("#hoverme-stop-2").mouseenter(function() { $(this) .find("img")

    .stop(true, true) .fadeOut(); });
  45. UGLY THE http://bugs.jquery.com/ticket/13103 JQUERY BOOLEAN TRAP $("#hoverme-stop-2").mouseenter(function() { $(this) .find("img")

    .stop({ clearQueue: true, jumpToEnd: true }) .fadeOut(); });
  46. UGLY THE http://bugs.jquery.com/ticket/13103 CASE CONSISTENCY var myRequest = new XMLHttpRequest();

  47. UGLY THE BOOLEAN TRAP event.initKeyEvent( "keypress", true, true, null, null,

    false, false, false, false, 9, 0 );
  48. SEE YOU COWBOY

  49. /caiogondim @caio_gondim me@caiogondim.com