$30 off During Our Annual Pro Sale. View Details »

Stripecon - Writing maintainable code

kay
September 21, 2018

Stripecon - Writing maintainable code

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

kay

September 21, 2018
Tweet

Other Decks in Technology

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. 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. 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