Swift 3 API Best Practices by Example

The slide of my "Swift 3 API Best Practices" talk at Cocoaheads Stockholm #74 https://www.meetup.com/CocoaHeads-Stockholm/events/234037606/

Transcript

1. Swift 3 API Best Practices by Reda Lemeden @kaishin
2. What does it mean to be Swifty?
3. 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.
4. Clarity over brevity.
5. Verbosity hurts readability.
6. Verbose Cryptic Lagom The sweet spot. https://en.wikipedia.org/wiki/Lagom
7. Let’s talk about naming.
8. Add just enough to not be ambiguous. Keep just enough to not be redundant. THE GOLDEN RULE
9. Clarity at the call site is more important than clarity at declaration.
10. 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)
11. 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)
12. Communicate roles, not types.
13. func frame(at index: Int) -> UIImage? func image(at index: Int) -> UIImage? frame(at: 2) image(at: 2) Declaration Call Site
14. func frame(at index: Int) -> UIImage? func image(at index: Int) -> UIImage? frame(at: 2) image(at: 2) Declaration Call Site
15. Rely on the type system and omit needless words.
16. func frame(at index: Int) -> UIImage? func frame(atIndex index: Int) -> UIImage? frame(at: 2) frame(atIndex: 2) Declaration Call Site
17. func frame(at index: Int) -> UIImage? func frame(atIndex index: Int) -> UIImage? frame(at: 2) frame(atIndex: 2) Declaration Call Site
18. Start argument labels with prepositions for better readability.
19. func frame(at index: Int) -> UIImage? func frameAt(_ index: Int) -> UIImage? frame(at: 2) frameAt(2) Declaration Call Site
20. func frame(at index: Int) -> UIImage? func frameAt(_ index: Int) -> UIImage? frame(at: 2) frameAt(2) Declaration Call Site
21. Start methods with nouns if they return a value.
22. func frame(at index: Int) -> UIImage? func decodeFrame(at index: Int) -> UIImage? frame(at: 2) decodeFrame(at: 2) Declaration Call Site
23. func frame(at index: Int) -> UIImage? func decodeFrame(at index: Int) -> UIImage? frame(at: 2) decodeFrame(at: 2) Declaration Call Site
24. Start your methods with verbs when they have side effects.
25. func prepareForAnimation() prepareForAnimation() Declaration Call Site func animationPreparation() animationPreparation()
26. func prepareForAnimation() prepareForAnimation() Declaration Call Site func animationPreparation() animationPreparation()
27. Aim for mimicking written English on the call site.
28. func frame(at index: Int) -> UIImage? func frame(aPosition index: Int) -> UIImage? frame(at: 2) frame(aPosition: 2) Declaration Call Site
29. func frame(at index: Int) -> UIImage? func frame(aPosition index: Int) -> UIImage? frame(at: 2) frame(aPosition: 2) Declaration Call Site
30. Use argument labels to add context to Foundation types.
31. func prepareForAnimation(with data: Data) prepareForAnimation(with: data) Declaration Call Site func prepareForAnimation(withGIFData data: Data) prepareForAnimation(withGIFData: data)
32. func prepareForAnimation(with data: Data) prepareForAnimation(with: data) Declaration Call Site func prepareForAnimation(withGIFData data: Data) prepareForAnimation(withGIFData: data)
33. Start factory methods with the verb ‘make’ to express outcome.
34. func animatedFrame(with newImage: UIImage?) -> AnimatedFrame frame.animatedFrame(with: image) Declaration Call Site func makeAnimatedFrame(with newImage: UIImage?) -> AnimatedFrame frame.makeAnimatedFrame(with: image)
35. func animatedFrame(with newImage: UIImage?) -> AnimatedFrame frame.animatedFrame(with: image) Declaration Call Site func makeAnimatedFrame(with newImage: UIImage?) -> AnimatedFrame frame.makeAnimatedFrame(with: image)
36. Use ‘ed’ or ‘ing’ suffixes for mutating methods.
37. func constrain(by size: CGSize) size.constrain(by: size) Declaration – CGSize Extension Call Site func constrained(by size: CGSize) size.constrained(by: size)
38. func constrain(by size: CGSize) size.constrain(by: size) Declaration – CGSize Extension Call Site func constrained(by size: CGSize) size.constrained(by: size)
39. filling(_ size: CGSize) size.filling(size) Declaration – CGSize Extension Call Site fill(_ size: CGSize) size.fill(size)
40. filling(_ size: CGSize) size.filling(size) Declaration – CGSize Extension Call Site fill(_ size: CGSize) size.fill(size)
41. Write boolean properties as affirmative assertions.
42. var animating: Bool view.animating Declaration Call Site var isAnimating: Bool View.isAnimating var isNotAnimating: Bool var notAnimating: Bool view.notAnimating View.isNotAnimating
43. var animating: Bool view.animating Declaration Call Site var isAnimating: Bool View.isAnimating var isNotAnimating: Bool var notAnimating: Bool view.notAnimating View.isNotAnimating
44. For the love of everything that’s holy, avoid abbreviations.
45. func frameDur(prop: GIFProperties) -> Double? frameDur(prop: properties) Declaration Call Site func frameDuration(with properties: GIFProperties) -> Double? frameDuration(with: properties)
46. func frameDur(prop: GIFProperties) -> Double? frameDur(prop: properties) Declaration Call Site func frameDuration(with properties: GIFProperties) -> Double? frameDuration(with: properties)
47. UpperCamelCase for types, lowerCamelCase otherwise.
48. Either UPPERCASE acronyms or lowercase them. Don’t mix both.
49. var GifImageSource: CGImageSource Declaration var GIFImageSource: CGImageSource var gifImageSource: CGImageSource
50. 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)
51. 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)
52. Develop good habits.
53. Always document your code. A must for code meant to be used by others (SDKs, open-source, etc.)
54. Editor > Structure > Add Documentation (alt+cmd+/)
55. Add commonly-used defaults for parameters.
56. 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))
57. When in doubt, look at Cocoa and Foundation for inspiration.
58. 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