Writing Code for Humans, not Computers

RENÉ CACHEAUX • MOBILE ARCHITECT • ATLASSIAN • @RCACHATX

Coding for Humansnot computers

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

What’s the big deal?

Readable = Fun

Code is Hard to Read

Time is MoneyWe 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?

🤐

• Big cool statistic

• 2,569

• Add-Ons in Marketplace

Tabs vs Spaces


• 2,569


Prototypes


• 2,569



• 2,569


Let’s Dive In

C O D I N G F O R H U M A N S

S TAT E O F A F FA I R S

P U T T I N G I N TO P R A C T I C E

Agenda




Agenda

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.

State of Affairs

We Read A Lot

Smart CompilersLike, really smart.

When developing, we spend most time reading.

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.

R O B E R T C . M A R T I N , C L E A N C O D E : A H A N D B O O K O F A G I L E S O F T WA R E C R A F T S M A N S H I P

“

”

Opening a Project

Someone, somewhere is

reading your code from 5 years ago…




Agenda


• 2,569


So what can we do about it?

Design Great Reading Experiences

Humans are complexWe all come from different cultures, different backgrounds, and different skill levels.

We ❤ Patterns




Agenda




Agenda

Coding for Humans

Writing Code

Structuring Code

Building ProjectsFinding code quickly and welcoming newcomers.

Dividing code up to make code easy to understand.

Writing code that’s easy to read.

Coding for Humans

Writing Code

Structuring Code





• 2,569


On-boarding

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

PatternsArchitectureOrganization Vocabulary

What should go in a README?


• 2,569


Organizing Source

Before you can read something you have to

find the code.

Tell a Story Mapping View Controllers as Packages

Organizing Source

Robert Martin, ‘Uncle Bob’

Screaming Architecture

Example

Welcome Twitter

Sign Up

Log In

User’s Journey

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

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

Callout

App Tab Bar

Callout

App Tab Bar

Nav Bar

Tabs

Follows vertical placement on screen.

Callout

App Tab Bar

Nav Bar

Search Compose Search Compose Search Compose

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

More examples of view controllers as packages.

Callout

App Tab Bar

Tabs

Follows left to right positioning of tabs.

Callout

App Tab Bar

Home Tab

Nav Bar

Nav Stack

Home Tab Actions

Home tab navigation based group organization.

Connect

Nav Bar

Home tab’s nav bar connect item.

Open Tweet Detail

Nav Stack

Home Tab Navigation

Tweet List Tweet Detail

Groups organized by nav stack order.

Mapping App to Source Organization

Temporal Physical

Re-usable Code

Re-usable code organized separately.

Screaming Architecture

What app is this?

What app is this?

Organize by domain instead of by technology.

Why use this?

Easier to manageEasy to Find CodeEasy to Read Cleaner Diffs

Why use this?

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

Coding for Humans

Writing Code

Structuring Code




6666

UNDERLYING PRINCIPLE

Make it easy for you and your team to find code.

Coding for Humans

Writing Code

Structuring Code




Coding for Humans

Writing Code

Structuring Code





• 2,569


View Controllers as Components

Component-based software engineering … is a reuse-based approach to defining, implementing and composing loosely coupled independent components into systems.W I K I P E D I A

“

”

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.V I E W C O N T R O L L E R P R O G R A M M I N G G U I D E F O R I O S , A P P L E

“

”

Independent Loosely Coupled

Life of a Typical View Controller

🙈

Instead

View Controller Package

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

Break it Down

Child View Controller

Child View Controller

Break it Down

Cell Actions

Cell Actions

Break it Down

Each Cell as a View Controller

View controller containment is your friend 😍!

Why use this?

Easy to Read Single Responsibility

Incremental & Parallelize

Why use this?


• 2,569


Use Cases

… 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.W I K I P E D I A

“

”

Like TweetRefresh Tweet ListLog In Create Tweet

Twitter Use Cases

How can I use this?

Use Case + Command Pattern

Object-Oriented Software Engineering: A Use Case Driven Approach

Robert Martin, ‘Uncle Bob’

Use Case + Command Pattern

Use Case + NSOperation💑

Check out Apple’s ‘Concurrency

Programming Guide’


• 2,569


Think of them as a recipe

Types of NSOperations

Sync (default) Async

Like TweetRefresh Tweet ListLog In Create Tweet

Twitter Use Cases

Twitter Use Cases

What typically goes into a Use Case NSOperation?

Notify to ReactNSData -> ModelsHTTP Get Persist Models

Typical Refresh Use Case

View controllers create & schedule use cases.

Cell View Controller

Cell Actions

Cell Actions

Why use this?

TestableReusableEasy to Read Flexibility

Why use this?

Coding for Humans

Writing Code

Structuring Code




104104


Architecture plays a significant role. Pick one and stick with it.

Coding for Humans

Writing Code

Structuring Code




Coding for Humans

Writing Code

Structuring Code





• 2,569


Writing Code

Example

Negated condition.

Nested multiple levels.

Has to run at the end.

Positive condition & removed one level of nesting.

Will always run at the end of the method.

Silly NSNotification user info access.

New KeyboardAnimation type with failable initializer.

New KeyboardAnimation type with failable initializer.

Animation looks very generic, not specific to this method.

New method added to UIView via extension.

New method added to UIView via extension.

Still too many nested levels! 2 levels deep.

Removed one level with a guard.

Removed another level by moving logic into updateComposeFeedbackViewBottomConstraintConstant()

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

Simplified by extending UIWindow.

Simplified by extending UIWindow.

NSNotification is more of a distraction here.

Moved into new method that takes the keyboard animation.

Moved into new method that takes the keyboard animation.

Oh yea, and one last thing…

Before

After

The Art of Readable Code

Stay PositiveReturn EarlyAvoid Nesting Create New Types

Best Practices we Used

{ return <T> +

Optional ChainingGuardFailable Initializers Defer

Swifty Things we Used

? g { d { .?

Tons of other Swifty things…

Swift API Design Guidelines

Why use this?

Easy to Read

Why use this?


• 2,569


Interface Builder 🙈

Coding for Humans

Writing Code

Structuring Code




163163


Writing is hard, spend time researching and experimenting.

Coding for Humans

Writing Code

Structuring Code




Coding for Humans

Writing Code

Structuring Code







Agenda


• 2,569


So those are just a few tips and tricks, where to go from here?




Agenda




Agenda

Putting into Practice

Putting into Practice

Automate

Code Review

Team Buy-inThe 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.

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




Agenda




That’s It

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

Less BugsFunDeliver FasterSlow at first, lightning fast once established.

It’s fun when it’s easy to read and build.

More team members will understand.

Benefits


• 2,569


Shoot for the moon!

Thank you! 🍻

RENÉ CACHEAUX • MOBILE ARCHITECT • ATLASSIAN • @RCACHATX

Don’t forget to grab a handout.