Swift 3 API Best Practices by Example

Slide 1

Slide 1 text

Swift 3 API Best Practices by Reda Lemeden @kaishin

Slide 2

Slide 2 text

What does it mean to be Swifty?

Slide 3

Slide 3 text

Why? • Consistency with Cocoa/Foundation. Apple is leading by example. • Conventions make code easier to read and review. • Improving clarity and readability. • Paramount for open-source maintainers.

Slide 4

Slide 4 text

Clarity over brevity.

Slide 5

Slide 5 text

Verbosity hurts readability.

Slide 6

Slide 6 text

Verbose Cryptic Lagom The sweet spot. https://en.wikipedia.org/wiki/Lagom

Slide 7

Slide 7 text

Let’s talk about naming.

Slide 8

Slide 8 text

Add just enough to not be ambiguous. Keep just enough to not be redundant. THE GOLDEN RULE

Slide 9

Slide 9 text

Clarity at the call site is more important than clarity at declaration.

Slide 10

Slide 10 text

func frame(at index: Int) -> UIImage? func f(_ i: Int) -> UIImage? func frame(_ i: Int) -> UIImage? func frame(_ index: Int) -> UIImage? func frame(atIndex index: Int) -> UIImage? frame(at: 2) f(2) frame(2) frame(2) frame(atIndex: 2) Declaration Call Site func frameAtIndex(index: Int -> UIImage? frameAtIndex(index: 2)

Slide 11

Slide 11 text

Slide 12

Slide 12 text

Communicate roles, not types.

Slide 13

Slide 13 text

func frame(at index: Int) -> UIImage? func image(at index: Int) -> UIImage? frame(at: 2) image(at: 2) Declaration Call Site

Slide 14

Slide 14 text

func frame(at index: Int) -> UIImage? func image(at index: Int) -> UIImage? frame(at: 2) image(at: 2) Declaration Call Site

Slide 15

Slide 15 text

Rely on the type system and omit needless words.

Slide 16

Slide 16 text

func frame(at index: Int) -> UIImage? func frame(atIndex index: Int) -> UIImage? frame(at: 2) frame(atIndex: 2) Declaration Call Site

Slide 17

Slide 17 text

func frame(at index: Int) -> UIImage? func frame(atIndex index: Int) -> UIImage? frame(at: 2) frame(atIndex: 2) Declaration Call Site

Slide 18

Slide 18 text

Start argument labels with prepositions for better readability.

Slide 19

Slide 19 text

func frame(at index: Int) -> UIImage? func frameAt(_ index: Int) -> UIImage? frame(at: 2) frameAt(2) Declaration Call Site

Slide 20

Slide 20 text

func frame(at index: Int) -> UIImage? func frameAt(_ index: Int) -> UIImage? frame(at: 2) frameAt(2) Declaration Call Site

Slide 21

Slide 21 text

Start methods with nouns if they return a value.

Slide 22

Slide 22 text

func frame(at index: Int) -> UIImage? func decodeFrame(at index: Int) -> UIImage? frame(at: 2) decodeFrame(at: 2) Declaration Call Site

Slide 23

Slide 23 text

func frame(at index: Int) -> UIImage? func decodeFrame(at index: Int) -> UIImage? frame(at: 2) decodeFrame(at: 2) Declaration Call Site

Slide 24

Slide 24 text

Start your methods with verbs when they have side effects.

Slide 25

Slide 25 text

func prepareForAnimation() prepareForAnimation() Declaration Call Site func animationPreparation() animationPreparation()

Slide 26

Slide 26 text

func prepareForAnimation() prepareForAnimation() Declaration Call Site func animationPreparation() animationPreparation()

Slide 27

Slide 27 text

Aim for mimicking written English on the call site.

Slide 28

Slide 28 text

func frame(at index: Int) -> UIImage? func frame(aPosition index: Int) -> UIImage? frame(at: 2) frame(aPosition: 2) Declaration Call Site

Slide 29

Slide 29 text

func frame(at index: Int) -> UIImage? func frame(aPosition index: Int) -> UIImage? frame(at: 2) frame(aPosition: 2) Declaration Call Site

Slide 30

Slide 30 text

Use argument labels to add context to Foundation types.

Slide 31

Slide 31 text

func prepareForAnimation(with data: Data) prepareForAnimation(with: data) Declaration Call Site func prepareForAnimation(withGIFData data: Data) prepareForAnimation(withGIFData: data)

Slide 32

Slide 32 text

func prepareForAnimation(with data: Data) prepareForAnimation(with: data) Declaration Call Site func prepareForAnimation(withGIFData data: Data) prepareForAnimation(withGIFData: data)

Slide 33

Slide 33 text

Start factory methods with the verb ‘make’ to express outcome.

Slide 34

Slide 34 text

func animatedFrame(with newImage: UIImage?) -> AnimatedFrame frame.animatedFrame(with: image) Declaration Call Site func makeAnimatedFrame(with newImage: UIImage?) -> AnimatedFrame frame.makeAnimatedFrame(with: image)

Slide 35

Slide 35 text

Slide 36

Slide 36 text

Use ‘ed’ or ‘ing’ suffixes for mutating methods.

Slide 37

Slide 37 text

func constrain(by size: CGSize) size.constrain(by: size) Declaration – CGSize Extension Call Site func constrained(by size: CGSize) size.constrained(by: size)

Slide 38

Slide 38 text

func constrain(by size: CGSize) size.constrain(by: size) Declaration – CGSize Extension Call Site func constrained(by size: CGSize) size.constrained(by: size)

Slide 39

Slide 39 text

filling(_ size: CGSize) size.filling(size) Declaration – CGSize Extension Call Site fill(_ size: CGSize) size.fill(size)

Slide 40

Slide 40 text

filling(_ size: CGSize) size.filling(size) Declaration – CGSize Extension Call Site fill(_ size: CGSize) size.fill(size)

Slide 41

Slide 41 text

Write boolean properties as affirmative assertions.

Slide 42

Slide 42 text

var animating: Bool view.animating Declaration Call Site var isAnimating: Bool View.isAnimating var isNotAnimating: Bool var notAnimating: Bool view.notAnimating View.isNotAnimating

Slide 43

Slide 43 text

var animating: Bool view.animating Declaration Call Site var isAnimating: Bool View.isAnimating var isNotAnimating: Bool var notAnimating: Bool view.notAnimating View.isNotAnimating

Slide 44

Slide 44 text

For the love of everything that’s holy, avoid abbreviations.

Slide 45

Slide 45 text

func frameDur(prop: GIFProperties) -> Double? frameDur(prop: properties) Declaration Call Site func frameDuration(with properties: GIFProperties) -> Double? frameDuration(with: properties)

Slide 46

Slide 46 text

func frameDur(prop: GIFProperties) -> Double? frameDur(prop: properties) Declaration Call Site func frameDuration(with properties: GIFProperties) -> Double? frameDuration(with: properties)

Slide 47

Slide 47 text

UpperCamelCase for types, lowerCamelCase otherwise.

Slide 48

Slide 48 text

Either UPPERCASE acronyms or lowercase them. Don’t mix both.

Slide 49

Slide 49 text

var GifImageSource: CGImageSource Declaration var GIFImageSource: CGImageSource var gifImageSource: CGImageSource

Slide 50

Slide 50 text

var GifImageSource: CGImageSource Declaration var GIFImageSource: CGImageSource var gifImageSource: CGImageSource func prepareForAnimation(withGIFData data: Data) func prepareForAnimation(withGifData data: Data) func prepareForAnimation(withgifData data: Data)

Slide 51

Slide 51 text

Slide 52

Slide 52 text

Develop good habits.

Slide 53

Slide 53 text

Always document your code. A must for code meant to be used by others (SDKs, open-source, etc.)

Slide 54

Slide 54 text

Editor > Structure > Add Documentation (alt+cmd+/)

Slide 55

Slide 55 text

Add commonly-used defaults for parameters.

Slide 56

Slide 56 text

func prepareForAnimation(withGIFNamed name: String, size: CGSize = .zero, contentMode: UIViewContentMode? = nil) Declaration func prepareForAnimation(withGIFNamed: “cocoaheads”) Call Site func prepareForAnimation(withGIFNamed: “cocoaheads”, size: CGSize(width: 1, height: 1))

Slide 57

Slide 57 text

When in doubt, look at Cocoa and Foundation for inspiration.

Slide 58

Slide 58 text

Useful Links Session 403 - WWDC ‘16: https://developer.apple.com/videos/play/wwdc2016/403/ Swift API Design Guidelines: https://swift.org/documentation/api-design-guidelines/ SE-0023 - Swift Evolution: https://github.com/apple/swift-evolution/ blob/master/proposals/0023-api-guidelines.md