Coding Practices - EP1SE1 The Good, The Bad and The Ugly

Discussing coding best practices and what we need to be aware of to make things easier and be kinder to our code base's future developer. We'll chat about comments, variable names, refactoring, planning, building and more.

Transcript

1. GOOD, BAD & UGLY CODING PRACTICES - EP1 S1
3. “ANY FOOL CAN WRITE CODE THAT A COMPUTER CAN UNDERSTAND. GOOD PROGRAMMERS WRITE CODE THAT HUMANS CAN UNDERSTAND.” - John Johnson (a real guy)
4. CODING PRACTICES SOFTWARE CRAFTMANSHIP Remember what our grandparents told us: ▸ Anything worth doing is worth doing well. ▸ Slow and steady wins the race. ▸ Measure twice cut once. ▸ Practice, Practice, Practice.
5. TEXT TECHNIQUES FOR SELF-DOCUMENTING CODE We can split the techniques for self-documenting code into three broad categories: structural - where the structure of code or directories is used to clarify the purpose naming related - such as function or variable syntax related - where we make use of (or avoid using) features of the language to clarify code.
6. STRUCTURAL
7. // square root of n with Newton-Raphson approximation r = n / 2; while (Math.abs(r - (n / r)) > t) { r = 0.5 * (r + (n / r)); } console.log("r = " + r); MOVE CODE INTO A FUNCTION
8. // Improved function SquareRootApproximation(num) { const root = num / 2; while (Math.abs(root - (num / root)) > t) { root = 0.5 * (root + (num / root)); } return root; } console.log("root = " + SquareRootApproximation(144)); MOVE CODE INTO A FUNCTION
9. // from if (!el.offsetWidth || !el.offsetHeight) { } // to function isVisible(el) { return el.offsetWidth && el.offsetHeight; } if (!isVisible(el)) { } REPLACE CONDITIONS WITH FUNCTION
10. // from if (!el.offsetWidth || !el.offsetHeight) { } // to var isVisible = el.offsetWidth && el.offsetHeight; if (!isVisible) { } REPLACE CONDITIONS WITH VARIABLE
11. NAMING
12. TEXT RENAMING FUNCTIONS There’s some simple rules that you can follow: ‣ Avoid using vague words like “handle” or “manage” - handleLinks(), manageObjects() ‣ Use active verbs - cutGrass(), sendFile() — functions that actively perform something. ‣ Indicate return value - getMagicBullet(), readFile(). where it makes sense. ‣ Languages with strong typing can use type signatures to help indicate return values as well.
13. // BAD! var btn = { clckEvnt: () => {} }; var ctrl_pnl = new CtrlPnl(btn); // GOOD :) var button = { clickEvent: () => {} }; var controlPanel = new ControlPanel(button); VARIABLE NAMING
14. SYNTAX
15. // Merges data with original set, // if boolean === true myThing.setData({ x: 1 }, true); // Much cleaner myThing.mergeData({ x: 1 }); AVOID BOOLEAN FLAGS
16. // A good example of this in JavaScript are the array iteration methods: var ids = []; for(var i = 0; i < things.length; i++) { ids.push(things[i].id); } USING LANGUAGE FEATURES
17. // Compare it with using map(): var ids = things.map(function(thing) { return thing.id; }); USING LANGUAGE FEATURES
18. To Comment or Not to Comment…
19. /* set the value of the age integer to 32 */ var age = 32; USELESS COMMENTING
20. /* set the value of the age integer to 32 */ var age = 32; USELESS COMMENTING
21. /* * Replaces with spaces * the braces in cases * where braces in places * cause stasis. **/ $str = str_replace(array("\{","\}")," ",$str); USELESS COMMENTING
22. If your feel your code is too complex to understand without comments, it’s probably just bad. Rewrite it until it doesn’t need comments any more. If, at the end of that effort, you still feel comments are necessary, then by all means, add comments. Carefully. Jeff Atwood ANOTHER FAMOUS QUOTE BY SOME GUY
23. KEEP CALM & STAY DRY
24. // A good example: elemCollection[i].style.color = "red"; elemCollection[i].style.backgroundColor = "blue"; elemCollection[i].style.border = "2px solid #000"; elemCollection[i].style.paddingLeft = "3px"; elemCollection[i].style.marginTop = "3px"; elemCollection[i].style.fontSize = "1.2em"; elemCollection[i].style.fontStyle = "italic"; DRY - DON’T REPEAT YOURSELF!
25. // …could be expressed in a much cleaner way: applyCSS(elemCollection[i], { color: "red", backgroundColor: "blue", border: "2px solid #000", paddingLeft: "3px", marginTop: "3px", fontSize: "1.2em", fontStyle: "italic" }); DRY - DON’T REPEAT YOURSELF!
26. // or function applyCSS(el, styles) { for (var prop in styles) { if (!styles.hasOwnProperty || styles.hasOwnProperty(prop)) { el.style[prop] = styles[prop]; } } return el; } DRY - DON’T REPEAT YOURSELF!