Designing JS APis

The Good, The Bad, and the Ugly

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