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
   

   View Slide

2. INTRODUCTION
   INTRODUCTION
   Kay van Baarle
   OGD ict-diensten
   CTO So ware (june 2018)
   Silverstripe 2.4 ~ 3.5(?)
   2
   

   View Slide

3. BEFORE THAT
   3
   

   View Slide

4. THE CODE HORROR
   4
   

   View Slide

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
   

   View Slide

6. SO I STARTED WONDERING..
   SO I STARTED WONDERING..
   WHY?
   WHY?
   6
   

   View Slide

7. WHAT MAKES CODE
   MAINTAINABLE?
   7
   

   View Slide

8. CODE STYLE / CONVENTIONS
   CODE STYLE / CONVENTIONS
   There are no bad conventions!
   8
   

   View Slide

9. ARCHITECTURE
   ARCHITECTURE
   Code structure
   What goes where
   So ware architecture
   How does it all connect
   9
   

   View Slide

10. DOCUMENTATION
    DOCUMENTATION
    Use README's for ease in project setup
    Write down the planned architecture
    Write down code styles / conventions / etc.
    10
    

    View Slide

11. AVOID (OVER)COMPLEXITY
    AVOID (OVER)COMPLEXITY
    Code should be read like a book
    KISS
    11
    

    View Slide

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
    

    View Slide

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
    

    View Slide

14. REPLACABILITY
    REPLACABILITY
    Avoid entangling your project with stuff you might
    want to replace
    14
    

    View Slide

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
    

    View Slide

16. GETTING STARTED WITH
    GETTING STARTED WITH
    WRITING MAINTAINABLE CODE!
    WRITING MAINTAINABLE CODE!
    16
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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; jvar 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
    

    View Slide

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
    

    View Slide

21. ABRA-CADABRA C0DE
    WRITTEN BY A WIZARD
    WRITTEN BY A WIZARD ...OR SOMETHING
    ...OR SOMETHING
    21
    

    View Slide

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; jvar 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
    

    View Slide

23. AVOID SIDE EFFECTS, TRY TO RETURN
    AVOID SIDE EFFECTS, TRY TO RETURN
    SOMETHING
    SOMETHING
    23
    

    View Slide

24. SET VARIABLES WHERE THEY BELONG
    SET VARIABLES WHERE THEY BELONG
    24
    

    View Slide

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; jvar a = arr.slice(0); // clone arr
    a.push(arg[i][j]);
    if (i==max)
    ...
    }
    }
    ...
    }
    25
    

    View Slide

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, helperIvar a = arr.slice(0); // clone arr
    a.push(arg[helperI][j]);
    if (i===maxLength)
    ...
    }
    }
    ...
    }
    26
    

    View Slide

27. MAGIC VARIABLES
    MAGIC VARIABLES
    LIKE NUMBERS, STRINGS, ETC
    LIKE NUMBERS, STRINGS, ETC
    27
    

    View Slide

28. MAGIC VARIABLES
    LIKE NUMBERS, STRINGS, ETC
    28
    

    View Slide

29. DON'T REPEAT YOURSELF
    DON'T REPEAT YOURSELF
    DO REPEAT
    DO REPEAT
    YOURSELF!
    YOURSELF!
    29
    

    View Slide

30. INCOMPLETE UNIT TESTING
    INCOMPLETE UNIT TESTING
    Code coverage doesn't say everything
    30
    

    View Slide

31. View Slide

32. SOME RULES TO
    SOME RULES TO
    CODE BY
    CODE BY
    32
    

    View Slide

33. AVOID COMMON MISTAKES
    AVOID COMMON MISTAKES
    Don't apply magic
    To DRY or not to DRY
    Don't rely on God
    33
    

    View Slide

34. GO FOR READABLE CODE!
    GO FOR READABLE CODE!
    34
    

    View Slide

35. THE FLYING V
    35
    

    View Slide

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
    

    View Slide

37. CATCH/RETURN EARLY
    CATCH/RETURN EARLY
    OR AVOID HAVING TO RETURN EARLY AT ALL
    OR AVOID HAVING TO RETURN EARLY AT ALL
    37
    

    View Slide

38. BE DEFENSIVE IN YOUR
    BE DEFENSIVE IN YOUR
    PROGRAMMING
    PROGRAMMING
    Try / catch shows uncertainties in your code
    Use them wisely
    38
    

    View Slide

39. AVOID LOCK-INS BY LIBRARIES
    AVOID LOCK-INS BY LIBRARIES
    AND PACKAGES
    AND PACKAGES
    39
    

    View Slide

40. Single responsibility principle
    Open/closed principle
    Liskov substitution principle
    Interface segregation principle
    Dependency inversion principle
    40
    

    View Slide

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
    

    View Slide

42. View Slide

43. HOW TO KEEP WRITING
    HOW TO KEEP WRITING
    MAINTAINABLE CODE?
    MAINTAINABLE CODE?
    43
    

    View Slide

44. THINK AHEAD!
    THINK AHEAD!
    Work out how you like to implement thing and discuss
    this with your team
    44
    

    View Slide

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
    

    View Slide

46. MONITOR YOUR CODE
    MAINTAINABILITY
    46
    

    View Slide

47. KEEP YOUR DOCS UP-TO DATE
    KEEP YOUR DOCS UP-TO DATE
    REVIEW YOUR STYLE GUIDE /
    REVIEW YOUR STYLE GUIDE /
    CONVENTIONS
    CONVENTIONS
    47
    

    View Slide

48. HELP.. MY CODE
    HELP.. MY CODE
    BASE IS !@#$
    BASE IS !@#$
    WHAT TO DO NOW?
    WHAT TO DO NOW?
    48
    

    View Slide

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
    

    View Slide

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
    

    View Slide

51. NEVER KEEP CONTRIBUTING TO
    NEVER KEEP CONTRIBUTING TO
    UNMAINTAINABLE CODE
    UNMAINTAINABLE CODE
    Use by-passes with maintainability in mind
    51
    

    View Slide

52. APPLY ALL THAT YOU'VE LEARNED
    APPLY ALL THAT YOU'VE LEARNED
    TODAY, AND SPREAD THE WORD
    TODAY, AND SPREAD THE WORD
    52
    

    View Slide

53. TAKE AWAYS
    TAKE AWAYS
    Setup code conventions and coding styles
    Document the planned code structure and
    architecture
    Avoid common mistakes
    53
    

    View Slide

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
    

    View Slide

55. MAKE CODE MAINTAINABILITY
    MAKE CODE MAINTAINABILITY
    NEGOTIABLE
    NEGOTIABLE
    55
    

    View Slide

56. FURTHER TIPS
    FURTHER TIPS
    Design Patterns (Gang of Four)
    Learn (some) functional programming
    Simple made Easy (Rich Hickey)
    56
    

    View Slide

57. THANKS!
    THANKS!
    57
    

    View Slide

58. QUESTIONS?
    58
    

    View Slide

59. f`
    

    View Slide