Stripecon - Writing maintainable code

Presentation for Stripecon 2018 @ Enschede
Writing maintainable code in an ever growing environment

Transcript

1. WRITING WRITING MAINTAINABLE CODE MAINTAINABLE CODE IN AN EVER GROWING ENVIRONMENT IN AN EVER GROWING ENVIRONMENT Stripecon 2018 - Enschede 1
2. INTRODUCTION INTRODUCTION Kay van Baarle OGD ict-diensten CTO So ware (june 2018) Silverstripe 2.4 ~ 3.5(?) 2
3. BEFORE THAT 3
4. THE CODE HORROR 4
5. WHAT BAD CODE BASES SHARE WHAT BAD CODE BASES SHARE No structure, whatsoever Different coding styles... even in the same line Lack of any form of architecture Unreadable 5
6. SO I STARTED WONDERING.. SO I STARTED WONDERING.. WHY? WHY? 6
7. WHAT MAKES CODE MAINTAINABLE? 7
8. CODE STYLE / CONVENTIONS CODE STYLE / CONVENTIONS There are no bad conventions! 8
9. ARCHITECTURE ARCHITECTURE Code structure What goes where So ware architecture How does it all connect 9
10. DOCUMENTATION DOCUMENTATION Use README's for ease in project setup Write down the planned architecture Write down code styles / conventions / etc. 10
11. AVOID (OVER)COMPLEXITY AVOID (OVER)COMPLEXITY Code should be read like a book KISS 11
12. COMMENTS IN CODE COMMENTS IN CODE ARE THE SOURCE OF ARE THE SOURCE OF GREAT EVIL GREAT EVIL ..EXCEPT WHEN IT COMES TO DOCS ..EXCEPT WHEN IT COMES TO DOCS ...OR RESOURCES, MAGIC AND OTHER STUFF LIKE THAT ...OR RESOURCES, MAGIC AND OTHER STUFF LIKE THAT 12
13. UNIT TESTING UNIT TESTING Some form of documentation Proper unit tests (not just happy flow) Eases refactoring Use it in your C.I. 13
14. REPLACABILITY REPLACABILITY Avoid entangling your project with stuff you might want to replace 14
15. Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. — John F. Woods, 1991 15
16. GETTING STARTED WITH GETTING STARTED WITH WRITING MAINTAINABLE CODE! WRITING MAINTAINABLE CODE! 16
17. Non understandable (variable) naming According to: // A has no meaning, whatsoever $a = [ "Bella" ,"Lucy" , "Daisy" ]; // Variable is self explaing $top_3_most_popular_female_dog_names = [ "Bella" ,"Lucy" ,"Daisy" ]; wideopenpets.com 17
18. Non understandable (variable) naming // Abbreviation is not clear // $thing doesn't make it any better either $trans_cost = get_trans_cost($thing); // Now we now it are transaction costs $transaction_cost = get_trans_cost($thing); 18
19. UNSURE WHY SOME CODE WORKS UNSURE WHY SOME CODE WORKS function cartesian(arg) { var r = [], max = arg.length-1; function helper(arr, i) { for (var j=0, l=arg[i].length; j<l; j++) { var a = arr.slice(0); // clone arr a.push(arg[i][j]); if (i==max) r.push(a); else helper(a, i+1); } } helper([], 0); return r; } 19
20. UNSURE WHY SOME CODE WORKS UNSURE WHY SOME CODE WORKS // Cartesian shuffle in order to generate all possible combina // see: https://stackoverflow.com/q/33524132 function cartesian(arg) { var r = [], max = arg.length-1; ... } helper([], 0); return r; } 20
21. ABRA-CADABRA C0DE WRITTEN BY A WIZARD WRITTEN BY A WIZARD ...OR SOMETHING ...OR SOMETHING 21
22. ABRA-CADABRA CODE ABRA-CADABRA CODE function cartesian(arg) { var r = [], max = arg.length-1; function helper(arr, i) { for (var j=0, l=arg[i].length; j<l; j++) { var a = arr.slice(0); // clone arr a.push(arg[i][j]); if (i==max) r.push(a); else helper(a, i+1); } } helper([], 0); return r; } 22
23. AVOID SIDE EFFECTS, TRY TO RETURN AVOID SIDE EFFECTS, TRY TO RETURN SOMETHING SOMETHING 23
24. SET VARIABLES WHERE THEY BELONG SET VARIABLES WHERE THEY BELONG 24
25. SET VARIABLES WHERE THEY BELONG SET VARIABLES WHERE THEY BELONG function cartesian(arg) { var r = [], max = arg.length-1; function helper(arr, i) { for (var j=0, l=arg[i].length; j<l; j++) { var a = arr.slice(0); // clone arr a.push(arg[i][j]); if (i==max) ... } } ... } 25
26. SET VARIABLES WHERE THEY BELONG SET VARIABLES WHERE THEY BELONG function cartesian(arg) { var result = []; function helper(arr, i) { var maxLength = args[i].length - 1; for (var helperI = 0, helperI<setLength; helperI++) { var a = arr.slice(0); // clone arr a.push(arg[helperI][j]); if (i===maxLength) ... } } ... } 26
27. MAGIC VARIABLES MAGIC VARIABLES LIKE NUMBERS, STRINGS, ETC LIKE NUMBERS, STRINGS, ETC 27
28. MAGIC VARIABLES LIKE NUMBERS, STRINGS, ETC 28
29. DON'T REPEAT YOURSELF DON'T REPEAT YOURSELF DO REPEAT DO REPEAT YOURSELF! YOURSELF! 29
30. INCOMPLETE UNIT TESTING INCOMPLETE UNIT TESTING Code coverage doesn't say everything 30
32. SOME RULES TO SOME RULES TO CODE BY CODE BY 32
33. AVOID COMMON MISTAKES AVOID COMMON MISTAKES Don't apply magic To DRY or not to DRY Don't rely on God 33
34. GO FOR READABLE CODE! GO FOR READABLE CODE! 34
35. THE FLYING V 35
36. The Flying V for (var i = 0; i < array.lenght; i++) { for (var nestedArrI = 0; nestedArrI < array[i].length; i++ if (array[i][nestedArrI] === true) { while (1 == 1) { switch(array[i][nestedArrI]) { case X: if (...) { ... } } } } } } } 36
37. CATCH/RETURN EARLY CATCH/RETURN EARLY OR AVOID HAVING TO RETURN EARLY AT ALL OR AVOID HAVING TO RETURN EARLY AT ALL 37
38. BE DEFENSIVE IN YOUR BE DEFENSIVE IN YOUR PROGRAMMING PROGRAMMING Try / catch shows uncertainties in your code Use them wisely 38
39. AVOID LOCK-INS BY LIBRARIES AVOID LOCK-INS BY LIBRARIES AND PACKAGES AND PACKAGES 39
40. Single responsibility principle Open/closed principle Liskov substitution principle Interface segregation principle Dependency inversion principle 40
41. UNIT TESTING UNIT TESTING Don't just go for code coverage, go for case coverage Have a bug? Add a unit test Good code is testable 41
43. HOW TO KEEP WRITING HOW TO KEEP WRITING MAINTAINABLE CODE? MAINTAINABLE CODE? 43
44. THINK AHEAD! THINK AHEAD! Work out how you like to implement thing and discuss this with your team 44
45. DON'T BE THE ROCKSTAR DON'T BE THE ROCKSTAR YOUR CODE IS ONLY AS MAINTAINABLE YOUR CODE IS ONLY AS MAINTAINABLE AS THE MOST JUNIOR DEV IN YOUR TEAM AS THE MOST JUNIOR DEV IN YOUR TEAM 45
46. MONITOR YOUR CODE MAINTAINABILITY 46
47. KEEP YOUR DOCS UP-TO DATE KEEP YOUR DOCS UP-TO DATE REVIEW YOUR STYLE GUIDE / REVIEW YOUR STYLE GUIDE / CONVENTIONS CONVENTIONS 47
48. HELP.. MY CODE HELP.. MY CODE BASE IS !@#$ BASE IS !@#$ WHAT TO DO NOW? WHAT TO DO NOW? 48
49. DON'T PANIC DON'T PANIC Rome wasn't buid in a day... maintainability comes with small steps Try to get your technical depth in scope 49
50. USE BUG FIXES / SMALL FEATURES TO USE BUG FIXES / SMALL FEATURES TO IMPROVE YOUR CODE IMPROVE YOUR CODE Don't forget to add unit tests 50
51. NEVER KEEP CONTRIBUTING TO NEVER KEEP CONTRIBUTING TO UNMAINTAINABLE CODE UNMAINTAINABLE CODE Use by-passes with maintainability in mind 51
52. APPLY ALL THAT YOU'VE LEARNED APPLY ALL THAT YOU'VE LEARNED TODAY, AND SPREAD THE WORD TODAY, AND SPREAD THE WORD 52
53. TAKE AWAYS TAKE AWAYS Setup code conventions and coding styles Document the planned code structure and architecture Avoid common mistakes 53
54. TAKE AWAYS TAKE AWAYS Setup linters, both for Dev-enviroment and C.I. Ensure your code stays readable and comprehensible Keep evaluating your code maintainability and keep technical depth in scope 54
55. MAKE CODE MAINTAINABILITY MAKE CODE MAINTAINABILITY NEGOTIABLE NEGOTIABLE 55
56. FURTHER TIPS FURTHER TIPS Design Patterns (Gang of Four) Learn (some) functional programming Simple made Easy (Rich Hickey) 56
57. THANKS! THANKS! 57
58. QUESTIONS? 58
59. f`