Communicating Code - Windy City Rails 2015

The code you write is like your handwriting. It makes sense to you, but others might not understand what you write or why you write it. In many ways, writing code is the easy part. Ensuring that your colleagues understand your intentions is more difficult.

This talk will focus on how to communicate effectively in your code.

Transcript

1. Kyle Crum - Senior Developer / Team Lead reverb.com twitter: @kylecrum email: kyle@reverb.com Communicating Code
4. 1. Sellers List Item
5. 1. Sellers List Item 2. Buyers Purchase Item
6. 1. Sellers List Item 2. Buyers Purchase Item 3. Profit
8. 1. Sellers List Item
9. 1. Sellers List Item 2….15 Humans being Humans.
10. 1. Sellers List Item 2….15 Humans being Humans. 16. Profit
11. Why do I care about communication?
12. Code is for people.
13. People need to understand.
14. Misunderstanding
15. Misunderstanding Bugs
16. Misunderstanding Bugs Less Coding Time
17. Unclear Code = Less Efficiency
18. Even Businesses Agree Moar efficiency = moar good
19. Unclear code
20. Unclear code Sugar?
21. Unclear code Puppy? Sugar?
22. Unclear code Puppy? Sugar?
23. Clear Code
24. Design Principles
25. Design Principles S O L I D
26. Design Principles S O L I D Single Responsibility Open/Closed Liskov Substitution Interface Segregation Dependency Inversion
27. Design Principles S O L I D Single Responsibility Open/Closed Liskov Substitution Interface Segregation Dependency Inversion KISS
28. Design Principles S O L I D Single Responsibility Open/Closed Liskov Substitution Interface Segregation Dependency Inversion KISS DRY
29. Design Principles S O L I D Single Responsibility Open/Closed Liskov Substitution Interface Segregation Dependency Inversion KISS YAGNI DRY
30. KISS my SOLID YAGNI!
31. Just communicate.
32. 2 Things to communicate
33. 2 Things to communicate 1. What you are doing.
34. 2 Things to communicate 1. What you are doing. 2. Why you are doing it.
35. The “What”
36. Ruby can be artistic
37. Ruby can be artistic
39. Ruby can be artistic
41. Sometimes it’s too much
43. code != art
44. code == a_manual
45. code == a_manual
46. How can we make code more manual-like?
47. Class naming
48. 2 kinds of classes
49. 2 kinds of classes • Things (models, views, controllers, view models). Has state.
50. 2 kinds of classes • Things (models, views, controllers, view models). Has state. • Processes
51. 2 kinds of classes • Things (models, views, controllers, view models). Has state. • Processes Easy Naming
52. 2 kinds of classes • Things (models, views, controllers, view models). Has state. • Processes Hard Naming Easy Naming
53. When we do the easy thing..
55. Refund Part
56. Refund Part Charge Part
57. Refund Part Void Part Charge Part
58. Break into processes instead
59. Naming Process Classes
60. Naming Process Classes 1.
61. Naming Process Classes 1. 2.
62. ?
63. ? Existential Crisis!
64. ?
65. ? Is Person?
66. ? Is Person? Is Machine?
67. ? Is Person? Is Machine? ?
68. What does this say?
69. What does this say? • Has state
70. What does this say? • Has state • Can be passed as argument / variable
71. Is that what I want to say?
72. Probably not.
73. One step away from..
74. One step away from..
75. Instead…
76. Verb “process” classes
77. Easier to spot naming smells
78. Easier to spot naming smells • what does it do?
79. Easier to spot naming smells • what does it do? • what is it executing?
81. • clearly says “what”
82. • clearly says “what” • constrains ability to bloat
83. Still too generic!
84. Still too generic! For all the times?
85. Namespace!
86. Namespace!
87. Namespace! Not lib
88. Namespace! Not lib Used during checkout
89. Namespace!
90. Namespace! The What
91. Namespace! The What The Why
92. Methods
93. Yell at Rails section
96. Is href?
97. Is href? Is href?
98. Is href? Is href? ID of?
99. Let’s time travel!
100. Let’s time travel! …and bring ruby 2.0
102. Is content!
103. Is content! href required!
104. Is content! href required! HTML Attributes!
105. vs.
106. vs.
107. No reason not to use key-value arguments
108. No reason not to use key-value arguments* * Ruby > 2 only
109. Key-value arg all the things!
111. +
113. Things needed
114. Things needed Things I can do
115. All kinds of space!
116. ok?
118. • All code executes
119. • All code executes • Does not add to the understanding.
120. = =
121. = =
124. Too much communication?
125. Probably
126. Probably* * But who cares?
127. More communication > Less communication
128. More clarity > Less clarity
129. Before
130. Before
131. Refund Void Charge Add
132. Inside the methods..
135. Read the code out loud
143. Code is fun to read again!
144. Let’s talk about meta- programming
147. What methods does it have?
148. False Economy
149. False Economy • You saved on typing.
150. False Economy • You saved on typing. • Everyone else spends more time reading/ understanding.
152. Methods!
153. Meta programming as salt
154. Just a little
155. Too much…
156. The “Why”
157. Why “The Why”?
158. Why “The Why”? 1. Empathy
159. Why “The Why”? 1. Empathy 2. See #1
160. All Code Starts
161. But becomes…
162. How the did this get here?
163. Commit Messages
164. Bad Commit messages Fix Bug
165. Bad Commit messages Fix Bug What
166. Bad Commit messages Fix Bug What Why?
167. Bad Commit messages Fix Bug What Why?
168. Good Commit Messages
169. Good Commit Messages Handle payments of $0 With a marketing promotion, some buyers are able to buy low-cost, free shipping items for free. - Skip credit card processing when >= $0 - Create a payment for $0 for tracking
170. Good Commit Messages Handle payments of $0 With a marketing promotion, some buyers are able to buy low-cost, free shipping items for free. - Skip credit card processing when >= $0 - Create a payment for $0 for tracking What
171. Good Commit Messages Handle payments of $0 With a marketing promotion, some buyers are able to buy low-cost, free shipping items for free. - Skip credit card processing when >= $0 - Create a payment for $0 for tracking What Why
173. Reads Code
174. Reads Code
175. Reads Code git log
176. Reads Code git log
177. You have the space! Use it!
178. Code Comments
179. This seems wrong
180. This seems wrong
181. This seems wrong Ah, ok
182. Bad Comments
183. Bad Comments Same
184. Bad Comments Same Doesn’t help understanding.
186. “What happened?”
187. “What happened?” “2 cars hit each other"
188. Good Comments Added info
189. Empathy is important!
190. Empathy is important! Read bad code
191. Empathy is important! Read bad code Knows why it is bad
192. Knowing why = having empathy
193. When we know what and why
194. When we know what and why • Understand the code better.
195. When we know what and why • Understand the code better. • Understand each other better
196. When we know what and why • Understand the code better. • Understand each other better • Happier, more productive team.
197. When we know what and why • Understand the code better. • Understand each other better • Happier, more productive team. • Programming is fun!
199. twitter: @kylecrum email: kyle@reverb.com