Here Be Dragons: The Hidden Gems of Technical Debt

How do you find the most unmaintainable code in your codebase? What will you prioritize in your next technical debt spike, and why?

In this talk you will learn how you can use RubyCritic, SimpleCov, Flog, Reek, and Skunk to slay dragons in your next refactoring adventure! Find out how the relationship between churn, complexity, and code coverage can give you a common language to talk about code quality and increase trust in your code.

Presented at RubyConf Mini 2022.

Transcript

1. Here Be Dragons: The Hidden Gems of Tech Debt Ernesto Tagwerker (@etagwerker) RubyConf Mini, November 2022
2. 🤓 My pronouns are he/him
3. 🇦🇷 Hi, I’m from Argentina
5. 🦅 I live in Philadelphia
7. 👨💻 I love Ruby & Open Source!
9. 👪 Thanks to my sponsors!
10. Teo, Claire, and Luli
11. Founder & CTO @OmbuLabs & @FastRubyIO
12. Open Source Contributor/Maintainer rubycritic; skunk; bundler-leak; next_rails
13. Here Be Dragons (Story Time)
14. “hic sunt dracones”
15. “here be dragons”
16. By Abraham Ortelius - The Library of Congress, Public Domain
17. By Abraham Ortelius - The Library of Congress, Public Domain
18. “Be careful with this part of the world, nobody has been there, there may be monsters.”
20. The Hunt-Lenox Globe
21. Credit: Rare Book Division, The New York Public Library
22. Credit: University of Rochester
23. What if there was a map to your codebase?
24. “Be careful with this part of the world, nobody has been there, there may be monsters.”
25. “Be careful with this part of the codebase, nobody wants to touch it, there is a lot of tech debt.”
26. How do you fi nd these dragons in your codebase?
27. How do you fi nd tech debt in your codebase?
29. Tech Debt & Dragons
30. 1. The Complexity Dragon
31. 1. The Complexity Dragon 2. The Smelly Dragon
32. 1. The Complexity Dragon 2. The Smelly Dragon 3. The Shapeshifting Dragon
33. 1. The Complexity Dragon 2. The Smelly Dragon 3. The Shapeshifting Dragon 4. The Untested Dragon
34. The Complexity Dragon
36. Complexity 1 class Foo 2 def yay 3 a = eval "1+1" 4 if a == 2 5 puts "yay" 6 end 7 end 8 end
37. Complexity flog
38. Complexity “flog reports the most tortured code”
39. Complexity $ flog foo.rb 10.6: flog total
40. Complexity 1 class Foo 2 def yay 3 a = eval "1+1" # 1.2 + 6.0 4 if a == 2 # + 1.2 5 puts “yay" # + 1.2 6 end. # = 7 end. # 10.6 8 end
41. 55 ## flog.rb 56 # Eval forms 57 58 SCORES.merge!(:define_method => 5, 59 :eval => 5, 60 :module_eval => 5, 61 :class_eval => 5, 62 :instance_eval => 5) 63
42. 62 ## flog.rb 63 # Various "magic" usually used for "clever code" 64 65 SCORES.merge!(:alias_method => 2, 66 :extend => 2, 67 :include => 2, 68 :instance_method => 2, 69 :instance_methods => 2, 70 :method_added => 2, 71 :method_defined? => 2, 72 :method_removed => 2, 73 :method_undefined => 2, 74 :private_class_method => 2, 75 :private_instance_methods => 2, 76 :private_method_defined? => 2, 77 :protected_instance_methods => 2, 78 :protected_method_defined? => 2,
43. 37 ## flog.rb 38 # Various non-call constructs 39 40 OTHER_SCORES = { 41 :alias => 2, 42 :assignment => 1, 43 :block => 1, 44 :block_pass => 1, 45 :block_call => 1, 46 :branch => 1, 47 :lit_fixnum => 0.25, 48 :sclass => 5, 49 :super => 1, 50 :to_proc_icky! => 10, 51 :to_proc_lasgn => 15, 52 :yield => 1, 53 } 54
44. Flog won’t report: - Known code smells - Duplicated code - Code that constantly changes
45. The Smelly Dragon
47. Code Smells “Smells are indicators of where your code might be hard to read, maintain or evolve.”
48. Code Smells They are not necessarily wrong.
49. Code Smells For example: Duplicated code is a code smell.
50. Code Smells “Duplication is far cheaper than the wrong abstraction.” Sandi Metz
51. Code Smells Reek (github.com/troessner/reek)
55. 1 module Reek 2 module SmellDetectors 3 class UncommunicativeVariableName < BaseDetector 4 # 5 # Checks the given +context+ for uncommunicative names. 6 # 7 # @return [Array<SmellWarning>] 8 # 9 def sniff 10 variable_names.select do |name, _lines| 11 uncommunicative_variable_name?(name) 12 end.map do |name, lines| 13 smell_warning( 14 lines: lines, 15 message: "has the variable name '#{name}'", 16 parameters: { name: name.to_s }) 17 end 18 end
56. Code Smells 1 class Foo 2 def yay 3 a = eval "1+1" 4 if a == 2 5 puts "yay" 6 end 7 end 8 end
58. Reek $ gem install reek
59. Reek $ reek foo.rb
60. Code Smells $ reek foo.rb foo.rb -- 2 warnings: [1]:IrresponsibleModule: Foo has no descriptive comment [3]:UncommunicativeVariableName: Foo#yay has the variable name 'a'
61. Code Smells 1 class Foo 2 def yay 3 a = eval "1+1" 4 if a == 2 5 puts "yay" 6 end 7 end 8 end
62. Code Smells 1 class Foo 2 def yay 3 eval_result = eval "1+1" 4 if eval_result == 2 5 puts "yay" 6 end 7 end 8 end
63. Code Smells $ reek foo.rb foo.rb -- 1 warning: [1]:IrresponsibleModule: Foo has no descriptive comment
65. Code Smells $ reek foo.rb foo.rb -- 1 warning: [1]:IrresponsibleModule: Foo has no descriptive comment
66. Code Smells 1 class Foo 2 def yay 3 eval_result = eval "1+1" 4 if eval_result == 2 5 puts "yay" 6 end 7 end 8 end
67. Code Smells 1 --- 2 3 ### .reek.yml (Generic smell configuration) 4 5 detectors: 6 IrresponsibleModule: 7 enabled: false
68. Code Smells $ reek foo.rb Inspecting 1 fi le(s): .
70. Reek won’t report: - Is this file constantly changing? - Is this file super complex?
71. The Shapeshifting Dragon
73. Churn
74. Churn git
75. Churn $ git log --follow --format=%h foo.rb | cat 573c8f5 2ccc5b8 b447bc3
76. Churn $ git log --follow --format=%h foo.rb | cat 573c8f5 2ccc5b8 b447bc3 # Churn Count = 3
77. Churn (github.com/danmayer/churn)
78. Churn - Mercurial - Git - SVN
79. Churn minitest $ churn --start_date "12 years ago" -e rb
80. Churn - By itself it adds little value - Useful when combined with other metrics
81. How can we bring it all together? - Complexity - Code Smells - Churn
82. RubyCritic
83. "Cartography" for Rubyists RubyCritic (github.com/whitesmith/rubycritic)
84. RubyCritic $ gem install rubycritic
85. RubyCritic $ rubycritic
88. GPA Pie Graph GPA Grade (Cost)
89. GPA Pie Graph Costly Files: - Hard to understand
90. GPA Pie Graph Costly Files: - Hard to understand - Hard to maintain
91. RubyCritic’s Cost - Code Smells (reek) - Complexity (flog)
92. RubyCritic’s Cost module RubyCritic class AnalysedModule def cost smells.map(&:cost).inject(0.0, :+) + # From Reek (complexity / COMPLEXITY_FACTOR) # From Flog end end end
93. Churn vs. Complexity Churn (SCM) Complexity (flog)
94. Churn Complexity 50 0% 1 100_000
95. Churn Complexity 100 0% 1 100_000 user.rb (changed: 2 times; complexity: 100_000 FPs )
96. Churn Complexity 100 0% 1 100_000 account.rb account.rb (changed: 27 times; complexity: 100 FPs)
97. 100% 0% 1 100_000 Complexity Churn
98. 100% 0% 1 100_000 Complexity Churn
99. 100% 0% 1 100_000 “No dragons here.” ❤ Complexity Churn
100. 100% 0% 1 100_000 “No one understands these fi les but they work. So don’t change them.” Complexity Churn
101. 100% 0% 1 100_000 “[…], if the code never changes, it's not costing us money.” Sandi Metz Complexity Churn
102. 100% 0% 1 100_000 “These fi les are easy to understand but you need to change them often because of reasons…” Complexity Churn
103. 100% 0% 1 100_000 Complexity Churn “These fi les are complex and change a lot…”
104. 100% 0% 1 100_000 Complexity Churn “Sometimes a class becomes so complex that refactoring seems too dif fi cult.” Michael Feathers
106. 100% 0% 1 100_000 “Here be Dragons.” Complexity Churn “Here be Dragons.” “Here be Dragons.” “Here be Dragons.”
109. The Untested Dragon
111. Code Coverage SimpleCov (github.com/simplecov-ruby/simplecov)
112. Code Coverage # Gemfile group :test do gem "simplecov", require: false end
113. Code Coverage # spec/spec_helper.rb if ENV["COVERAGE"] == "true" require 'simplecov' SimpleCov.start do add_group "Libraries", "lib" add_filter "/spec/" track_files "**/*.rb" end end
114. Code Coverage $ COVERAGE=true rspec
117. Recap 1. The Complexity Dragon ( fl og) 2. The Smelly Dragon (reek) 3. The Shapeshifting Dragon (churn) 4. The Untested Dragon (simplecov)
118. Finding Dragons Example: User vs. Account Class
119. user.rb churn: 10 complexity: 10 smells: 10 Tech debt score: 1,000 (10*10*10)
120. account.rb churn: 10 complexity: 10 smells: 10 Tech debt score: 1,000 (10*10*10)
121. user.rb churn: 10 complexity: 10 smells: 10 Tech debt score: 1,000 (10*10*10) account.rb churn: 10 complexity: 10 smells: 10 Tech debt score: 1,000 (10*10*10)
122. User and Account have the same amount of tech debt
123. “Do they?”
124. user.rb churn: 10 complexity: 10 smells: 10 code_coverage: 0% Tech debt score: 100,000 (10*10*10) * 100
125. account.rb churn: 10 complexity: 10 smells: 10 code_coverage: 90% Tech debt score: 10,000 (10*10*10) * 10
126. user.rb churn: 10 complexity: 10 smells: 10 code_coverage: 0% Tech debt score: 100,000 account.rb churn: 10 complexity: 10 smells: 10 code_coverage: 90% Tech debt score: 10,000
127. User has more tech debt than Account
128. Code Smells vs. Complexity vs. Code Coverage
130. Cost
131. Cost - Code Smells (reek) - Complexity (flog)
132. Cost Code Coverage
133. What if we could calculate a new signal that combines both of them?
134. Cost Code Coverage SkunkScore
135. SkunkScore = f(cost, code_coverage)
136. Why Code Coverage? Files which lack tests are harder to maintain
137. Skunk (github.com/fastruby/skunk)
138. Skunk $ gem install skunk
139. Skunk $ skunk
142. Skunk def skunk_score return cost.round(2) if coverage == PERFECT_COVERAGE (cost * penalty_factor).round(2) end def penalty_factor PERFECT_COVERAGE - coverage.to_i end
143. Now we can fi nally draw our map!
144. Here be dragons Here be dragons Here be dragons Here be dragons Here be dragons
145. 100% 0% 1 100_000 Complexity Churn “Here be dragons.” “Here be dragons.” “Here be dragons.”
147. How to Slay Dragons
149. Dragon Slaying 101: - Define what’s a dragon
150. What’s a dragon? - Team discussion on “tech debt” - Toolkit configuration
151. Dragon Slaying 101: - Define what’s a dragon - Draw the map and place “here be dragons”
152. Dragon Slaying 101: - Define what’s a dragon - Draw the map and place “here be dragons” - Pick your battles based on metrics
153. Slaying the untested dragon
154. Slaying the untested dragon
155. Slaying the untested dragon
156. Slaying the smelly dragon
157. $ reek foo.rb foo.rb -- 2 warnings: [1]:IrresponsibleModule: Foo has no descriptive comment [3]:UncommunicativeVariableName: Foo#yay has the variable name 'a' Slaying the smelly dragon
158. $ reek foo.rb foo.rb -- 2 warnings: [1]:IrresponsibleModule: Foo has no descriptive comment [3]:UncommunicativeVariableName: Foo#yay has the variable name 'a' Slaying the smelly dragon
159. Slaying the smelly dragon
160. Slaying the complexity dragon
161. Slaying the complexity dragon
162. 1. Flog 2. Reek 3. Churn 4. SimpleCov 5. RubyCritic 6. Skunk
163. 8. Attractor 9. MetricFu 10. CodeClimate 11. CodeScene 12. Codacy 13. CodeCov 14. SonarQube 15. Flay 16. Sandi Meter 17. Coverband 18. Etc.. 1. Flog 2. Reek 3. Churn 4. SimpleCov 5. RubyCritic 6. Skunk 7. Rubocop
164. 1. Pick your dragons
165. 1. Pick your dragons 2. Pick your toolkit
166. 1. Pick your dragons 2. Pick your toolkit 3. Slay your dragons
167. Thank you! @etagwerker - https://speakerdeck.com/etagwerker
168. Resources 1. https://github.com/whitesmith/rubycritic 2.https://github.com/colszowka/simplecov 3.https://github.com/metricfu/metric_fu 4.https://github.com/julianrubisch/attractor 5.https://www.fastruby.io/blog/ruby/quality/code-quality-ruby- gems.html 6.https://www.reddit.com/r/ruby/comments/2bq092/rubycritic/ 7.http://jakescruggs.blogspot.com/2008/08/whats-good- fl og-score.html 8.http://ruby.sadi.st/Flog.html 9.https://github.com/makaroni4/sandi_meter
169. Resources 1.https://codeclimate.com/blog/deciphering-ruby-code-metrics/ 2.https://www.stickyminds.com/article/getting-empirical-about-refactoring 3.https://www.sandimetz.com/blog/2017/9/13/breaking-up-the-behemoth 4.https://github.com/troessner/reek 5.https://github.com/seattlerb/ fl ay 6.https://github.com/seattlerb/ fl og 7.http://www.sqa.net/iso9126.html 8.https://www.slideshare.net/mscottford/important-metrics-for-measuring-code-health 9.https://www.theatlantic.com/technology/archive/2013/12/no-old-maps-actually- say-here-be-dragons/282267/ 10.https://education.nationalgeographic.org/resource/here-be-dragons 11.https://resurrect3d.lib.rochester.edu/models/5bdc5e604270f527332282dd