How to design a great code reading experience for your Apple platform apps & Xcode projects.

1. RENÉ CACHEAUX • MOBILE ARCHITECT • ATLASSIAN • @RCACHATX
Coding for Humans
not computers

2. It’s not easy,
we don’t teach it,
it’s not natural.

3. What’s the
big deal?
Readable = Fun
Code is Hard to Read
Time is Money
We can get time back to do all the
things we love.
Code reviews, fixing bugs, adding
new features all require reading.
Easy to read code is fun to work
with and who doesn’t want fun?

4. 🤐

5. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Tabs vs Spaces

6. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Prototypes

7. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace

8. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Let’s Dive In

9. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

10. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

11. State of
Affairs
We get Acclimated
It works! Done 😌
Fast, Faster…
We are under constant pressure to
deliver fast.
Difference between problem solving
and building production code.
After years and years we get used
to things and don’t see an issue.

12. State of
Affairs
We Read A Lot
Smart Compilers
Like, really smart.
When developing, we spend most
time reading.

13. Indeed, the ratio of time spent reading versus
writing is well over 10 to 1. We are constantly
reading old code as part of the effort to write
new code. ...[Therefore,] making it easy to
read makes it easier to write.
ROBERT C. MARTIN,
CLEAN CODE: A HANDBOOK OF AGILE SOFTWARE CRAFTSMANSHIP
“
”

14. Opening a
Project

15. Someone,
somewhere is
reading your code
from 5 years ago…

16. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

17. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
So what can we do about it?

18. Design Great
Reading
Experiences

19. Humans are complex
We all come from different
cultures, different backgrounds,
and different skill levels.

20. We ❤ Patterns

21. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

22. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

23. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

24. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

25. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
On-boarding

26. README.md
Provide a high level overview of
how things are structured and
leave the details out.

27. PatternsArchitectureOrganization Vocabulary
What should go in a README?

28. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Organizing Source

29. Before you can read
something you have to
find the code.

30. Tell a Story Mapping View Controllers as
Packages
Organizing Source

31. Robert Martin,
‘Uncle Bob’

32. Screaming
Architecture

33. Example

34. Welcome
Twitter
Sign Up
Log In
User’s Journey

35. Follows user’s journey,
topmost being earliest and
bottommost being latest.

36. Each view controller has its
own group, acts like a
package.

37. Callout
App Tab Bar

39. Callout
App Tab Bar
Nav Bar
Tabs

40. Follows vertical placement
on screen.

41. Callout
App Tab Bar
Nav Bar

42. Search Compose Search Compose Search Compose

43. Global nav bar screens are
placed at the root, follows
placement left to right.

44. More examples of view
controllers as packages.

45. Callout
App Tab Bar
Tabs

46. Follows left to right
positioning of tabs.

47. Callout
App Tab Bar
Home Tab

48. Nav Bar
Nav Stack
Home Tab Actions

49. Home tab navigation based
group organization.

50. Connect
Nav Bar

51. Home tab’s nav bar
connect item.

52. Open Tweet Detail
Nav Stack

53. Home Tab Navigation
Tweet List Tweet Detail

54. Groups organized by
nav stack order.

55. Mapping App to Source Organization
Temporal Physical

56. Re-usable Code

57. Re-usable code
organized separately.

58. Screaming
Architecture

59. What app is this?

60. What app is this?

61. Organize by domain
instead of by
technology.

62. Why use this?

63. Easier to manageEasy to Find CodeEasy to Read Cleaner Diffs
Why use this?

64. Side Tip
We read code outside of Xcode, so
make sure to mirror Xcode project
group structure with file system.

65. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

66. 6666
UNDERLYING PRINCIPLE
Make it easy for you and your team to find code.

67. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

68. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

69. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
View Controllers as
Components

70. Component-based software engineering
… is a reuse-based approach to defining,
implementing and composing loosely
coupled independent components into
systems.
WIKIPEDIA
“
”

71. View controllers are the foundation of your
app’s internal structure … Because they play
such an important role in your app, view
controllers are at the center of almost
everything you do.
VIEW CONTROLLER PROGRAMMING GUIDE FOR IOS,
APPLE
“
”

72. Independent Loosely Coupled

73. Life of a Typical View Controller
🙈

74. Instead

75. View
Controller
Package

76. Dependencies
Anything not inside the view
controller’s group is an external
dependency. Try to inject.

77. Break it Down
Child View
Controller
Child View
Controller

78. Break it Down
Cell Actions
Cell Actions

79. Break it Down
Each Cell as a
View Controller

80. View controller
containment is your
friend 😍!

81. Why use this?

82. Easy to Read Single
Responsibility
Incremental &
Parallelize
Why use this?

83. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Use Cases

84. … a use case is a list of actions or event
steps, typically defining the interactions
between a role [user] and a system, to
achieve a goal.
WIKIPEDIA
“
”

85. Like TweetRefresh Tweet ListLog In Create Tweet
Twitter Use Cases

86. How can I use this?

87. Use Case + Command Pattern

88. Object-Oriented Software
Engineering: A Use Case
Driven Approach

89. Robert Martin,
‘Uncle Bob’

90. Use Case + Command Pattern

91. Use Case + NSOperation
💑

92. Check out Apple’s
‘Concurrency
Programming Guide’

93. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Think of them as a recipe

94. Types of NSOperations
Sync (default) Async

95. Like TweetRefresh Tweet ListLog In Create Tweet
Twitter Use Cases

96. Twitter
Use Cases

97. What typically goes
into a Use Case
NSOperation?

98. Notify to ReactNSData -> ModelsHTTP Get Persist Models
Typical Refresh Use Case

99. View controllers create
& schedule use cases.

100. Cell View Controller
Cell Actions
Cell Actions

101. Why use this?

102. TestableReusableEasy to Read Flexibility
Why use this?

103. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

104. 104104
UNDERLYING PRINCIPLE
Architecture plays a significant role.
Pick one and stick with it.

105. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

106. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

107. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Writing Code

108. Example

110. Negated condition.

111. Nested multiple levels.

112. Has to run at the end.

115. Positive condition &
removed one level of
nesting.

116. Will always run at the
end of the method.

118. Silly NSNotification user info access.

121. New KeyboardAnimation type with
failable initializer.

122. New KeyboardAnimation type with
failable initializer.

124. Animation looks very generic, not
specific to this method.

127. New method added to UIView
via extension.

128. New method added to UIView
via extension.

130. Still too many nested levels! 2 levels deep.

136. Removed one level with a guard.

137. Removed another level by moving logic into
updateComposeFeedbackViewBottomConstraintConstant()

139. Two lines look related. Guard is only making
sure there’s a window.

142. Simplified by extending UIWindow.

143. Simplified by extending UIWindow.

145. NSNotification is more of a distraction here.

147. Moved into new method that takes the
keyboard animation.

148. Moved into new method that takes the
keyboard animation.

150. Oh yea, and one last thing…

152. Before

153. After

154. The Art of
Readable Code

155. Stay PositiveReturn EarlyAvoid Nesting Create New Types
Best Practices we Used
{ return <T> +

156. Optional ChainingGuardFailable Initializers Defer
Swifty Things we Used
? g { d { .?

157. Tons of other
Swifty things…

158. Swift API
Design
Guidelines

159. Why use this?

160. Easy to Read
Why use this?

161. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Interface Builder 🙈

162. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

163. 163163
UNDERLYING PRINCIPLE
Writing is hard,
spend time researching and experimenting.

164. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

165. Coding for
Humans
Writing Code
Structuring Code
Building Projects
Finding code quickly and
welcoming newcomers.
Dividing code up to make code
easy to understand.
Writing code that’s easy to read.

166. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

167. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
So those are just a few tips and
tricks, where to go from here?

168. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

169. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

170. Putting into Practice

171. Putting into
Practice
Automate
Code Review
Team Buy-in
The entire team needs to row
together on this.
Be nit-picky at first, the team will get
a rhythm going.
Automate as much as possible
using scripts. Help and detection.

172. Re-organizing
Make sure to stop development
while re-organizing Xcode projects.

173. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
Agenda

174. CODING FOR HUMANS
STATE OF AFFAIRS
PUTTING INTO PRACTICE
That’s It

175. We are all engineers
We want to build 😀 things and we
want to do it in a reasonable time
so we can enjoy other hobbies
even coding.

176. Less BugsFunDeliver Faster
Slow at first, lightning
fast once established.
It’s fun when it’s easy
to read and build.
More team members
will understand.
Benefits

177. • Big cool statistic
• 2,56
9
• Add-Ons in Marketplace
Shoot for the moon!

178. Thank you! 🍻
RENÉ CACHEAUX • MOBILE ARCHITECT • ATLASSIAN • @RCACHATX
Don’t forget to grab a handout.