SoftwareEngineering.APIDesign.iOS

API Design for iOS/Mac (Objective-c Edition)

1. UI Control Library API的设计

和已有组件保持一致(例如: 使用标准的API, 模型，模式)可以使Developer更易理解。

Class interface

Rule1: 使用该平台常用/通用的术语或者名字 (Use the local dialect)

在编码前学习该平台的习俗或者惯例；学习并理解protocol, delegate, category分别是什么；遵循内存管理规则；

Rule2: 解耦的设计 (Design decoupled)

"Any component should be designed such that it’s not coupled to the project you created it for,

and if it’s a GUI control or view, it should at least display something by default." Ref[1]

Rule3: 必须的设置应该作为初始器的参数 (Required settings should be initializer parameters)

- (id)initWithDelegate:(id<MGTileMenuDelegate>)theDelegate; // required parameter; cannot be nil.

Rule4: 允许访问初始器的参数

@property (nonatomic, weak, readonly) id<MGTileMenuDelegate> delegate; // must be specified via initializer method.

Rule5: 为头文件添加注释 (Comment your header files (including defaults))

"you should briefly note default values beside properties or accessors" Ref[1]

@property (nonatomic) CGGradientRef tileGradient; // gradient to apply to tile backgrounds (default: a lovely blue)
@property (nonatomic) NSInteger selectionBorderWidth; // default: 5 pixels
@property (nonatomic) CGGradientRef selectionGradient; // default: a subtle white (top) to grey (bottom) gradient

Rule 6: 确保可以用3行代码来使用组件 (Get up and running in 3 lines)

这条值得商榷!

// Instantiate.
tileController = [[MGTileMenuController alloc] initWithDelegate:self];

// Configure.
tileController.dismissAfterTileActivated = NO; // to make it easier to play with in the demo app.

// Display.
[tileController displayMenuCenteredOnPoint:loc inView:self.view];

Rule 7: 组件的demo越小，反映组件越好 (A fat demo usually means a broken component)

Rule 8: 提前考虑并满足定制场景 (Anticipate customisation scenarios)

"I approach this by trying not to think of customisation at the instance-variable level,

but rather at the “aspect” level." Ref[1]

Rule 9: 更多的属性，更少的行为/方法 (More properties, fewer actions)

Rule 10: 在你的组件中使用存在的组件 (Use controls in your controls)

Rule 11: 考虑将便利方法暴露给developer (Convenient for you is convenient for me)

Rule 12: (Magic is OK. Numbers aren’t)

"What’s not OK, though, is needlessly putting mysterious raw values throughout your code, and it’s

especially not OK to expose that in the API." Ref[1]

Delegate and data-source protocols

Data-source Protocol关注的事项:

How many things do I have?

What’s the value for property Y of thing X?

Delegate 关注的事项:

Should this thing do that?

This thing is about to do that.

This thing just did that.

should, will, did

Rule 13: 限制required方法的数量 (Limit ‘required’ delegate methods)

"A well-designed component should need very, very few required delegate methods - just the

bare minimum to do whatever it does." Ref[1]

Rule 14: 为可访问性进行设计 (Design for accessibility)

"make things accessible" Ref[1]

accessibility programming VoiceOver

Rule 15: 为参数使用语义明确的对象 (Use semantic objects for parameters)

"If you’re asking for a date, don’t accept numbers - get an actual NSDate object. " Ref[1]

Rule 16: 当语义不合适时，可以使用增强API的方式 (Enhance the API if semantics don’t fit)

例如: "A contact list implemented with a table should have a contacts-related API" Ref[1]

Rule: 17 UI组件的高亮令人关注 (Highlighting is interesting)

Rule: 18 可选方法并不是一个承诺 (Optional methods aren’t a commitment)

"Many of us approach optional delegate methods as an either-or situation: if you don’t implement them,

you get the default behaviour, and if you do, then you’re totally responsible for what happens.

That’s not ideal." ref[1]

可选方法可能并没有返回我们期望的值。比如：我们期望可选方法返回一个UIColor对象，但是可选方法返回了nil。那么我们

跳回默认逻辑是更好的选择。

Rule 19: 总是指明谁在"讲话" (Always say who’s talking)

- (void)tileMenu:(MGTileMenuController *)tileMenu didActivateTile:(NSInteger)tileNumber; // zero-based tileNumber

- (void)tileMenuDidActivateTile:(NSInteger)tileNumber; // zero-based tileNumber
// Um, WHICH menu?

Rule 20: 把不同的参数放在前面 (Put distinguishing params first in query methods)

- (UIImage *)imageForTile:(NSInteger)tileNumber inMenu:(MGTileMenuController *)tileMenu; // zero-based tileNumber

- (UIImage *)tileMenu:(MGTileMenuController *)tileMenu imageForTile:(NSInteger)tileNumber;

但是Apple API确实和该Rule相反。例如：

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section

Rule 21: 将sender放在notification方法的第一个参数 (Put the sender first in notification methods)

"The One True Delegate Protocol, however, isn’t for queries but rather for notifications." Ref[1]

- (void)tileMenu:(MGTileMenuController *)tileMenu willSwitchToPage:(NSInteger)pageNumber; // zero-based pageNumber

Rule 22: If a convention is broken, throw it away (*)

Notification

"Notifications are the other half of delegate protocols. My position is that, if you’re using a delegate

protocol (you should, if it’s at all appropriate), then it’s incomplete until you add the notifications

that naturally follow from it." Ref[1]

Rule 23: 通知和delegate方法保持一致 (Notifications follow delegate methods)

"If you have a delegate method that tells the delegate about something happening, you should

usually provide a notification for that same purpose." Ref[1]

Rule 24: 为notification提供足够的数据 (Be generous with notifications’ userInfo)

"At the very least, you must ensure that all arguments provided to the corresponding delegate

method are wrapped up in the userInfo object." Ref[1]

Rule 25: 进行测试 (Test the hell out of it)

如果时间紧迫，可以减少feature来支持测试

Todo: article on releasing open source code

2. About iOS API Design

2.1 Aviary team’s best practices for developing APIs

"The design goals for an API are similar to those of a user interface: exposing the product’s features

and communicating how to use them." Ref[2]

2.1.1 编写的文档要遵守平台的约定。

2.1.2 平台一致性

"This manifests itself in long, descriptive method names, the organization of functionality around view controllers,

and design patterns like delegation and target-action. " Ref[2]

遵守Apple的Cocoa Touch规范: naming conventions and design patterns

2.1.3 SDK可以快速集成

2.1.4 选择合适工具: Best Pattern

"Choosing the best pattern makes your code both easier to understand and to use."

Delegate

"the delegate version breaks up the processing code into pieces and makes it more difficult to read and understand."

"Delegation is best suited for situations when the response to a notification relies primarily on the information

contained in the delegate method’s parameters."

2.1.5 提供默认值

"By providing a convenience initializer, the integrating developer does not need to consider the more advanced

options until their application demands them."

2.1.6 维护SDK的向后兼容性和版本信息

Reference

1. API Design
http://mattgemmell.com/api-design/
主要是UI方面库和API的设计

2. Best Practices for iOS API Design (Read Again)
https://blog.creativesdk.com/2015/03/best-practices-for-ios-api-design/
"Aviary team’s best practices for developing APIs"

Todo

1. google "how to design interface of library for iOS"

2. WWDC 2014 Session 416 (ToRead)

3. adobe creative sdk

4. Delegate vs. Block

google "delegate vs block ios"

4.1 stablekernel.com/blog/blocks-or-delegates/

4.2 Blocks: A Case Against Protocol Delegation
http://mysteriousdevs.tumblr.com/post/29415817039/blocks-a-case-against-protocol-delegation
4.3 Blocks vs Delegates – A Comparison
http://www.abdus.me/ios-programming-tips/blocks-vs-delegates-ios-comparison/
4.4 iOS blocks vs. selectors and delegates
http://bradcupit.tumblr.com/post/3431169229/ios-blocks-vs-selectors-and-delegates
4.5 http://www.slideshare.net/pohjus/ios-selectors-blocks-and-delegation
4.6 Communicating with Blocks in Objective-C
http://themainthread.com/blog/2012/09/communicating-with-blocks-in-objective-c.html
4.7 Lessons from iOS dev #2: Delegates are good, blocks are better
https://programmingthomas.wordpress.com/2013/04/21/lessons-from-ios-dev-2-delegates-are-good-blocks-are-better/
4.8 Blocks vs Delegate
http://corinnekrych.blogspot.tw/2013/06/blocks-vs-delegate.html
4.9 Wrapping Objective-C Delegates with Blocks, Part 1
http://pivotallabs.com/wrapping-delegates-blocks/
4.10 When to use Delegation, Notification, or Observation in iOS
http://blog.shinetech.com/2011/06/14/delegation-notification-and-observation/
4.11 Replace common iOS delegate APIs with blocks
https://gist.github.com/puppybits/1523687
4.12 Delegate VS Block in API Design
http://wangling.me/2014/01/delegate-vs-block-in-api-design.html
4.13 Communication Patterns
http://www.objc.io/issues/7-foundation/communication-patterns/
4.14 Objective C Blocks: Summary, Syntax & Best Practices
http://amattn.com/p/objective_c_blocks_summary_syntax_best_practices.html
5. Delegate vs. Notification

google "ios delegate vs notification"

6. Single Responsibility Principle & iOS (To Debug the sample)
https://bendyworks.com/single-responsibility-principle-ios/