Optimizing For Readability

What do software engineers do all day long? Write code? Of course! But what about reading code, about understanding what’s happening? Aren’t we doing that even more? I believe we do. Because of that code should be as readable as possible! But what does that even mean? How do we achieve readable code? This talk will introduce you to coding principles and techniques that will help you write more readable code, be more productive and have more fun!

Transcript

1. View Slide

2. We write code
   

   View Slide

3. Isn't it more
   about reading?
   

   View Slide

4. Written once – read many
   times
   

   View Slide

5. „(…) when you program, you have to think
   about how someone will read your code,
   not just how a computer will interpret it.“
   Kent Beck
   

   View Slide

6. „Any fool can write code that a computer
   can understand. Good programmers write
   code that humans can understand.“
   Martin Fowler
   

   View Slide

7. Not about architecture
   

   View Slide

8. Methods & Code
   

   View Slide

9. Nurturing a code base
   

   View Slide

10. Extra effort
    

    View Slide

11. Save time!
    

    View Slide

12. Your code base?
    

    View Slide

13. View Slide

14. It's about joy!
    

    View Slide

15. Optimizing for Readability
    Tobias Pfeiffer
    @PragTob
    pragtob.info
    

    View Slide

16. Crazy?
    

    View Slide

17. Methods & Code
    

    View Slide

18. View Slide

19. Keep It Simple Stupid
    

    View Slide

20. Are comments a smell?
    

    View Slide

21. Comments are an excuse of
    the code that it could not be
    clearer.
    

    View Slide

22. Outdated comments are the
    worst
    

    View Slide

23. The why not the what
    

    View Slide

24. def paint_control(event)
    # some painting code
    rescue => e
    # Really important to rescue here.
    Failures that escape this method
    # cause odd-ball hangs with no
    backtraces. See #559 for an example.
    #
    puts "SWALLOWED PAINT EXCEPTION ON
    #{@obj} - go take care of it: " + e.to_s
    puts 'Unfortunately we have to swallow
    it because it causes odd failures :('
    end
    

    View Slide

25. Also known as the smell that
    tries to make other smells
    seem ok
    

    View Slide

26. # do one thing
    ...
    ...
    ...
    ...
    ...
    # do another thing
    ...
    ...
    ...
    ...
    # do something more
    ...
    ...
    

    View Slide

27. # do one thing
    ...
    ...
    ...
    ...
    ...
    # do another thing
    ...
    ...
    ...
    ...
    # do something more
    ...
    ...
    

    View Slide

28. # do one thing
    ...
    ...
    ...
    ...
    ...
    # do another thing
    ...
    ...
    ...
    ...
    # do something more
    ...
    ...
    Cocepts
    

    View Slide

29. Method too long
    

    View Slide

30. Short Methods
    

    View Slide

31. <= 8 LOC
    

    View Slide

32. Extract Methods
    

    View Slide

33. do_one_thing
    do_another_thing
    do_something_more
    Cocepts
    

    View Slide

34. # context, outlet, times, time per
    step, state, data
    def pattern(c, o, t, l, s, d)
    # ...
    end
    

    View Slide

35. Incomprehensible names
    

    View Slide

36. # context, outlet, times, time per
    step, state, data
    def pattern(c, o, t, l, s, d)
    # ...
    end
    

    View Slide

37. # context, outlet, times, time per
    step, state, data
    def pattern(c, o, t, l, s, d)
    # ...
    end
    

    View Slide

38. Explanatory names
    

    View Slide

39. Naming is hard
    

    View Slide

40. def pattern(context, outlet, time,
    time_per_step, state,
    data)
    # ...
    end
    

    View Slide

41. Argument order dependency
    

    View Slide

42. Try to keep it to 2 parameters
    

    View Slide

43. Example
    

    View Slide

44. # allowed to drink?
    if customer.age >= 18
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{['cola', 'mate'].sample}?"
    end
    

    View Slide

45. # allowed to drink?
    if customer.age >= 18
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{['cola', 'mate'].sample}?"
    end
    

    View Slide

46. No magic numbers
    

    View Slide

47. NON_ALCOHOLIC_DRINKS = ['cola', 'mate']
    MIN_DRINKING_AGE = 18
    

    View Slide

48. # allowed to drink?
    if customer.age >= MIN_DRINKING_AGE
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{NON_ALCOHOLIC_DRINKS.sample}?"
    end
    

    View Slide

49. # allowed to drink?
    if customer.age >= MIN_DRINKING_AGE
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{NON_ALCOHOLIC_DRINKS.sample}?"
    end
    

    View Slide

50. # allowed to drink?
    if customer.age >= MIN_DRINKING_AGE
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{NON_ALCOHOLIC_DRINKS.sample}?"
    end
    

    View Slide

51. Query method
    

    View Slide

52. Intention revealing method
    

    View Slide

53. # ...
    text.color = red
    # ...
    

    View Slide

54. # ...
    text.color = red
    # ...
    

    View Slide

55. # ...
    highlight(text)
    # ...
    

    View Slide

56. def highlight(text)
    text.color = red
    end
    

    View Slide

57. def highlight(text)
    text.color = red
    text.underline = true
    update_highlights
    end
    

    View Slide

58. # ...
    text.color = red
    text.underline = true
    update_highlights
    # ...
    

    View Slide

59. # ...
    highlight(text)
    # ...
    

    View Slide

60. # allowed to drink?
    if customer.age >= MIN_DRINKING_AGE
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{NON_ALCOHOLIC_DRINKS.sample}?"
    end
    

    View Slide

61. # allowed to drink?
    if customer.age >= MIN_DRINKING_AGE
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{NON_ALCOHOLIC_DRINKS.sample}?"
    end
    

    View Slide

62. # allowed to drink?
    if customer.age >= MIN_DRINKING_AGE
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{NON_ALCOHOLIC_DRINKS.sample}?"
    end
    

    View Slide

63. # allowed to drink?
    if customer.age >= MIN_DRINKING_AGE
    say 'Okay'
    drink = prepare_drink requested_drink
    say 'here you go'
    hand_drink_over drink, customer
    else
    say 'I am sorry you are not legally
    allowed rather to drink here'
    say "Would you rather have a
    #{NON_ALCOHOLIC_DRINKS.sample}?"
    end
    

    View Slide

64. if allowed_to_drink_alcohol?(customer)
    serve_drink requested_drink,
    customer
    else
    propose_non_alcoholic_drink
    end
    

    View Slide

65. „If you have a good name for
    a method you don't need to
    look at the body.“
    Martin Fowler
    

    View Slide

66. „The easiest code to
    understand is the code you
    don't have to read at all.“
    Tom Stuart (Berlin)
    

    View Slide

67. prepare_drink requested_drink
    price = requested_drink.price
    check = Check.new
    check.add_price price
    say 'That whill be ' + check.total
    

    View Slide

68. prepare_drink requested_drink
    price = requested_drink.price
    check = Check.new
    check.add_price price
    say 'That whill be ' + check.total
    

    View Slide

69. prepare_drink requested_drink
    price = requested_drink.price
    check = Check.new
    check.add_price price
    say 'That whill be ' + check.total
    

    View Slide

70. Same level of abstraction in
    a method
    

    View Slide

71. prepare_drink requested_drink
    prepare_check requested_drink
    

    View Slide

72. Nice code formatting
    

    View Slide

73. @left ||= 0
    @top ||= 0
    @width ||= 1.0
    @height ||= 0
    

    View Slide

74. double character: 'something weird',
    stateMask: CTRL | modifier,
    KeyCode: character.downcase.ord
    

    View Slide

75. 80 character width limit
    

    View Slide

76. 80 character width limit
    

    View Slide

77. 80 character width limit
    

    View Slide

78. 80 character width limit
    

    View Slide

79. 80 character width limit
    

    View Slide

80. Identify concepts
    

    View Slide

81. One language
    

    View Slide

82. Don't Repeat Yourself
    

    View Slide

83. Nurturing a code base
    

    View Slide

84. Code bases detoriate
    

    View Slide

85. No broken windows!
    

    View Slide

86. View Slide

87. View Slide

88. Magical time?
    

    View Slide

89. The boyscout rule
    

    View Slide

90. View Slide

91. Opportunistic Refactoring
    

    View Slide

92. TDD
    

    View Slide

93. 80% Code Coverage
    

    View Slide

94. 20% is never executed
    

    View Slide

95. Code Review Culture
    

    View Slide

96. „Brown Bag“ lunches
    

    View Slide

97. Pair Programming
    

    View Slide

98. Reaping the benefits
    

    View Slide

99. Know when to break the rules
    

    View Slide

100. If you still like your code from
     two years ago,
     then you are not learning fast
     enough.
     

     View Slide

101. Enjoy writing readable code!
     Tobias Pfeiffer
     @PragTob
     pragtob.info
     

     View Slide

102. Sources
     ●
     The Pragmatic Programmer
     ●
     Smalltalk Best Practice Patterns
     ●
     Clean Code
     ●
     Practical Object Oriented Design in Ruby
     

     View Slide

103. Photo Credit
     ●
     http://officeimg.vo.msecnd.net/en-us/images/MP900439313.jpg
     ●
     http://officeimg.vo.msecnd.net/en-us/images/MC900021328.wmf
     ●
     http://www.osnews.com/story/19266/WTFs_m
     ●
     (CC BY-SA 2.0)
     – http://www.flickr.com/photos/83633410@N07/7658272558/in/photostream/
     – http://www.flickr.com/photos/83633410@N07/7658165122/
     – https://www.flickr.com/photos/93425126@N00/313056379/
     ●
     (CC BY-NC-ND 2.0)
     – http://www.flickr.com/photos/andih/86577529/
     – http://www.flickr.com/photos/12584908@N08/3293117576/
     – http://www.flickr.com/photos/jasonlparks/4525188865/
     – http://www.flickr.com/photos/20714221@N04/2293045156/
     – https://www.flickr.com/photos/eyewash/2603717864/
     – https://www.flickr.com/photos/stevie_gill/3950697539/
     – https://www.flickr.com/photos/randar/15787696685/
     ●
     http://www.flickr.com/photos/47833351@N02/5488791911/(CC BY-ND 2.0)
     ●
     (CC BY 2.0)
     – http://www.flickr.com/photos/barry_b/76055201/
     – http://www.flickr.com/photos/25165196@N08/7725273678/
     – http://www.flickr.com/photos/29254399@N08/3187186308/
     – https://www.flickr.com/photos/garryknight/5650367750/
     – https://www.flickr.com/photos/alper/10742816123/
     ●
     (CC BY-NC-SA 2.0)
     – http://www.flickr.com/photos/dolescum/7380616658/
     – http://www.flickr.com/photos/antonkovalyov/5795281215/
     – http://www.flickr.com/photos/doug88888/2792209612/
     – https://www.flickr.com/photos/denverjeffrey/4392418334/
     ●
     (CC BY-NC 2.0)
     – http://www.flickr.com/photos/37996583811@N01/5757983532/
     – http://www.flickr.com/photos/sevendead/5650065458/
     – https://www.flickr.com/photos/whitecatsg/3146092196/
     

     View Slide