Closures in API design

Given at Swift Summit: https://www.swiftsummit.com/

Speaker notes and image attribution: https://github.com/hpique/Talks/blob/master/Closures%20in%20API%20design/Closures%20in%20API%20design.md

Transcript

1. Closures In API design { @hpique }
4. Agenda 4 Closures 4 @autoclosure 4 @noescape 4 Default values
5. Closures are self-contained blocks of functionality
6. Using closures func showButton() { UIView.animateWithDuration(0.5, animations: { self.button.alpha = 1 }, completion: { finished in if finished { self.button.enabled = true } }) }
7. Trailing closures func showButton() { UIView.animateWithDuration(0.5, animations: { self.button.alpha = 1 }) { finished in if finished { self.button.enabled = true } } }
8. Closures capture the constants and variables used within
10. Before closures UIAlertView
11. func showQuestionAlert() { questionAlert = UIAlertView(title: "Question", message: "Pigeons are the new cats?", delegate: self, cancelButtonTitle: nil, otherButtonTitles: "No", "Coo!") questionAlert.show() }
12. // MARK: UIAlertViewDelegate func alertView(alertView: UIAlertView, clickedButtonAtIndex buttonIndex: Int) { if (alertView === questionAlert) { switch buttonIndex { ... } } } func alertView(alertView: UIAlertView, didDismissWithButtonIndex buttonIndex: Int) { if (alertView === questionAlert) { questionAlert = nil } }
13. After closures UIAlertController
14. func showQuestionAlert() { let controller = UIAlertController(title: "Question", message: "Pigeons are the new cats?", preferredStyle: .Alert) let no = UIAlertAction(title: "No", style: .Default) { _ in ... } controller.addAction(no) let yes = UIAlertAction(title: "Coo!", style: .Default) { _ in ... } controller.addAction(yes) self.presentViewController(controller, animated: true) { ... } }
15. Closures encourage code locality
16. Using closures in our APIs
17. @autoclosure
18. Inneficient and func getExpensiveBool() -> Bool { NSThread.sleepForTimeInterval(10.0) println("Birds!!!") return true } let result = and(false, getExpensiveBool()) > Birds!!!
19. Short-circuit with closures func and(left: Bool, getRight : () -> Bool) -> Bool { if !left { return false } return getRight() } let result = and(false, { return getExpensiveBool() }) >
20. Use @autoclosure for parameter values that might not be used
21. Adding @autoclosure func and(left: Bool, @autoclosure getRight: () -> Bool) -> Bool let result = and(false, getExpensiveBool()) >
22. @autoclosure in the Standard Library func &&<T : BooleanType>(lhs: T, @autoclosure rhs: () -> Bool) -> Bool func assert(@autoclosure condition: () -> Bool, _ message: @autoclosure () -> String = default, file: StaticString = default, line: UWord = default)
23. @noescape
24. Loop with closure func loop(duration: NSTimeInterval, reverse: Bool, animations: () -> Void)
25. Using loop class MYView: UIView { func animate() { loop(duration: 0.5, reverse: true) { self.scale(1.25) } } func scale(scale: Double) { ... } }
26. How long are we capturing self?
27. What does loop do? loop(duration: 0.5, reverse: true) { self.scale(1.25) } 4 Call animations on every cycle? 4 Call once, take snapshots and animate between them?
28. Use @noescape for closure parameters that will not outlive the function call
29. Adding @noescape func loop(duration: NSTimeInterval, reverse: Bool, @noescape animations: () -> Void)
30. No need for self class MYView: UIView { func doAnimations() { loop(duration: 0.5, reverse: true) { scale(1.25) } } func scale(scale: Double) { ... } }
31. @noescape in the Standard Library func reduce<U>(initial: U, combine: @noescape (U, Self.Generator.Element) -> U) -> U
32. @autoclosure implies @noescape
33. Forward compatibility 4 Removing @noescape might break user code 4 Only add if sure that the function will never call the closure asynchronously
34. Default values
35. Event callbacks in objective-C - (void)fetchImageWithSuccess:(void (^)(UIImage *image))successBlock failure:(void (^)(NSError *error))failureBlock;
36. Swift translation func fetchImage(success: (UIImage -> Void)?, failure: (NSError -> Void)?) fetchImage(success: { image -> Void in save(image) }, failure: nil)
37. nil as default func fetchImage(success: (UIImage -> Void)? = nil, failure: (NSError -> Void)? = nil) { ... if let success = success { success(image) } } fetchImage(success: { image -> Void in save(image) })
38. No optionals func fetchImage(success: UIImage -> Void, failure: NSError -> Void) fetchImage(success: { image -> Void in save(image) }, failure: { _ in })
39. Empty closure as default func fetchImage(success: UIImage -> Void = { _ in }, failure: NSError -> Void = { _ in }) { ... success(image) } fetchImage(success: { image -> Void in save(image) })
40. Global function as default func fetchImage(success: UIImage -> Void = noop failure: NSError? -> Void = noop)
41. Defining noop func noop() {} func noop<T>(value: T) {}
42. Defining noop func noop() {} func noop<T>(value: T) {} func noop<T>() -> T? { return nil }
43. Defining noop func noop() {} func noop<T>(value: T) {} func noop<T>() -> T? { return nil } func noop<T, S>(value: T) -> S? { return nil }
44. Trailing confusion fetchImage() { _ in // What closure is this? }
45. Consider the trailing closure when defining parameter order
46. Finally func fetchImage(failure: NSError -> Void = noop, success: UIImage -> Void = noop)
47. Damn you Xcode!
48. Damn you again Xcode!
49. Be mindful of how you API looks in code completion and Quick Documentation
50. Compensating with documentation /// Fetches an image. /// /// :param: failure Closure to be called on failure. Default: noop. /// :param: success Closure to be called on success. Default: noop. func fetchImage(failure: NSError -> Void = noop, success: UIImage -> Void = noop)
51. Closures encourage code locality Use @autoclosure for parameter values that might not be used Use @noescape for closure parameters that will not outlive the function call
52. Prefer no-op closures as default values for closure parameters Consider the trailing closure when defining parameter order Be mindful of how consumers will discover your APIs
53. Coming next fetchImage().onSuccess { image in save(image) }.onFailure { error in handle(error) }
54. BCPL: the origin of {} GET "libhdr" LET start() = VALOF $( writes("Hello, World!*n") RESULTIS 0 $) Created by Martin Richards in 1966.
55. Thank you! Questions?
56. Needs more Swift