组件接口(API)设计指南[2]－类接口(class interface)

*返回文件夹阅读其它章节: http://blog.csdn.net/cuibo1123/article/details/39894477

类接口(class interface)

    你可以參考MGTileMenu的接口文件。

    咱们以前谈论了一些接口的细节，这里，例举几个通用规则：

规则1：使用当前平台的描写叙述用语或构架

    一个最多见的API错误设计是使用外来的规则，API属于一个特定的平台和相关开发人员生态系统。

你不能使用不论什么其它不一样平台的描写叙述用语或构架，这会污染你当前的代码库，并破坏你同伴的工做效率。

    在编码前要充分了解你的目标平台和代码规范。好比，在IOS和OSX中。不使用异常机制处理错误。

统一命名规则(规则要足够具体，但是也要足够简洁)。

    了解什么是协议(protocol)。托付(delegate)，扩展(category)。始终在你的代码中使用术语。

遵照构造函数和析构函数的有关命名方案。遵照本地内存管理规则。

    就像在天然语言中词汇和语法是不可切割的同样，你的风格必需要符合指定平台。

 

规则2: 设计解耦

    设计时应该使组件和建立该组件的项目没有关联，假设是一个GUI组件或者视图。那么它应该显示一些默认内容。利用现有的框架做为指导，尽量让托付协议(delegateprotocols)等交互保持松散耦合，适当的使用通知。并注意良好的设计和命名规则。

    要作到这一点，为每个组件建立一个单独的測试项目是一个很是有效的方法。强迫组件仅仅使用本身的API。不要提取不相关的类之间的共同点。

    如下让咱们来看看类的接口。初始化方法是类接口中最重要的部分之中的一个，它决定用户怎样使用你的组件。

你的类需要对某些必要配置进行初始化。

因此，一个明显的规则例如如下：

规则3: 所需的初始化条件应该由參数提供 

    假设有什么必须的初始化设置，不要等待需要它的时候再去提供。而要在需要以前由初始化參数提供。

假设初始化没有获得所需的条件则立马返回空(nil)。

// 需要參数，不能是nil
- (id)initWithDelegate:(id<MGTileMenuDelegate>)theDelegate;

规则4: 赞成訪问初始化參数

    这是上一个规则的延续：切记不要把初始化时用户提供的參数隐藏在模块内部。要让用户可以訪问他们，并注意可否够以某种方式改动(清除、或以其它方式改动)。

//必须经过初始化方法指定
@property (nonatomic, weak, readonly) id<MGTileMenuDelegate>delegate; 

这是以上两条规则共同拥有的演示样例。

规则5: 凝视你的头文件 

    实际上，你不会老是提供独立的文档来讲明代码功能。

假设你不提供独立的文档，那么你的.h文件(以及演示程序)就是你的文档。他们应该被“适当”的凝视，这里所说的适当是指：

    1:足够具体，但是篇幅不要太长。

要足够简洁。

 

    2:针对专业人员(语言和词汇)。

所有假设必须足够安全慎重。不要胡扯。不要含糊不清。

    特别是，你应简要说明參数、属性的功能和默认值。让用户在头文件里很是easy检索代码功能，而不需要去看可执行代码部分。

//瓦片背景渐变(default:蓝)
@property (nonatomic) CGGradientReftileGradient;
// default: 5 pixels
@property (nonatomic) NSIntegerselectionBorderWidth;
// default:黑(底)白(顶)渐变
@property (nonatomic) CGGradientRefselectionGradient;

规则6: 集成到执行很少于3行代码

    你的类应该设计成仅仅需要很是少的代码就可以集成到项目(不包括托付/数据源协议等)。不包括代理(delegate)方法。你的用户应该仅仅使用三行代码就能够进行最简单的測试，这些行各自是：

    1:实例化

    2:基本配置。

    3:显示或激活它。

如下是来自MGTileMenu的相关代码演示：

// 实例化.
tileController = [[MGTileMenuControlleralloc] initWithDelegate:self];
// 配置.
tileController.dismissAfterTileActivated = NO; // 使它更easy播放
// 显示.
[tileControllerdisplayMenuCenteredOnPoint:locinView:self.view];

规则7: 一个繁杂的演示程序一般意味着组件功能零碎

    还有一个推论: 你的演示程序大小决定了组件的质量。演示程序越小越好。演示所需代码应该尽量的少而简单（但是也要在demo中适当的演示组件的定制化服务或功能）。

    使用一个空的Xcode模版，应该仅仅需要加入很是少的代码，就可以建立具备你的组件核心功能的应用。仅仅提供一个演示程序是不够的，还必须确保复制－粘贴你提供的演示样例程序后相同可以工做。

规则8: 设置预约方案 

    我开发应用程序的标准规则是不给用户提供配置选项，而是选择合理的默认值来适用大部分用户。

好的软件。老是会执拗己见。

    关于这一点。组件和应用程序有所不一样，因为组件的使用场景是不明白的。

固然，你可以让组件仅仅适用于特定的某一种状况，但一般咱们更但愿组件具备必定的灵活性。

你永远不知道其它开发人员会怎样使用你的组件。所以，你必须让它具备必定的通用性。

    细致考虑组件所支持的功能是很是重要的。

尤为要考虑依赖关系－不是在编译/连接时的依赖。而是逻辑功能与接口之间的依赖。个人作法是不在实例变量(成员)的层次去想这个问题。而是从“定制方案”的层次去想这个问题。

弄清楚你想让你的组件具有哪些定制方案？而后依据这些定制方案，来选择公开哪些属性给使用者。

    一个很是easy犯的错误是公开的配置项(接口)不足而削弱了某种功能，比方如下的一些样例：

    1:公开了宽度和高度设置，但是没有考虑圆角。

    2:公开了背景颜色的设置，但是没有考虑高亮时的背景色设置。

    3:公开了尺寸设置。但是没有考虑间距。

    这样的错误一般取决于具体的组件，试着从显示效果和功能的角度考虑属性之间的关系。从用户的角度来考虑问题。

要灵活易用。但不要放弃组件的特性。

// 解除菜单后瓦片被激活(YES; 默认)
@property (nonatomic) BOOLdismissAfterTileActivated;
// 右手模式(YES; 默认) 或左手模式(NO)
@property (nonatomic) BOOLrightHanded;
// 每个瓦片的宽高，单位:像素(默认72 像素)
@property (nonatomic) NSIntegertileSide;
// 瓦片间距, 单位:像素(默认: 20 像素)
@property (nonatomic) NSIntegertileGap;
// 瓷砖圆角的半径, 单位:像素(默认: 12.0 像素)
@property (nonatomic) CGFloatcornerRadius;

    让常识指引你。

找到哪些在70％的状况下都会使用的选项，并提供这些选项给用户。

 

规则9: 不少其它的特性。更少的操做 

    在我喜欢的组件中(当中一些是标准框架。一些是来自第三方的开源组件，也有我本身写的)，有一个常常出现的特性。组件所实现的功能(所有功能，从初始化到状态更新等)和公开的接口(存取器或本身定义方法等)存在必定的比例关系。

    这些组件差点儿老是用更少的操做(这不是指界面上的操做，而是接口)来实现不少其它的特性。MGTileMenu有一个初始化和四个功能方法(当中一个是还有一个接口的简化)，以它的特性和操做来讲，是四倍的比例关系。我以为这是一个不错的比例。在具备简洁有用的功能的同一时候，也能灵活的定制。

 // 參数不能为nil
- (id)initWithDelegate:(id<MGTileMenuDelegate>)theDelegate;
// 从0開始
- (CGPoint)displayMenuPage:(NSInteger)pageNumcenteredOnPoint:(CGPoint)centerPtinView:(UIView *)parentView;
- (void)dismissMenu;
// 从0開始
- (void)switchToPage:(NSInteger)pageNum;

 

规则10: 在你的控件中使用控件

    一个简化API的很是好的方法是：在你的组件中使用现有的组件。组件风格统一并不意味着你不能利用现有组件来构造新的组件(实际上这是一个良好的软件project基本原则)。

    好比UITableViewCell和UIButton的API如此简单。就是因为它们使用了子控件UILabels和UIImageViews。假设合适，你也可以这样作－并且暴露子控件，以便让你当前的类接口更加简洁一致。

    好比MGTileMenu中，瓦片是由UIButtons扩展的。与在本身定义视图中绘制并跟踪输入、提供訪问接口相比，这简化了很是多工做。

规则11: 你的便利方法也可能适合用户

    你必定会在创做组件期间加入一些便利的方法，而又本能的将它们设为私有(private)。

事实上。你可以考虑使用者在集成你的组件时是否会用到这些方法，以此来决定是否公开(public)它们。

    好比，我在MGTileMenu中建立了这些便利的功能：

CGRectMGMinimallyOverlapRects(CGRectinner, CGRectouter, CGFloatpadding);
//RGB色彩渐变
CGGradientRefMGCreateGradientWithColors(UIColor *topColorRGB, UIColor *bottomColorRGB);

    第一个是存储位置的结构，用于移动菜单，以便它在其父视图中可以全然可见(方便其它开发人员建立与他们本身的UI配套的菜单)。第二个是存储渐变色的结构，用于为菜单背景设置的图形渐变(当背景改变后。会经过托付通知调用者)。

 

规则12: 奇妙的效果是好的，奇妙的数字不是

    你早晚会在组件中放入一些奇特的东西。并但愿赋予不少其它像史蒂夫·乔布斯式的使人愉快的奇妙特性。

但我要说的是在你的代码中具备特殊含义的数字。一个最多见的样例就是-1，它通常用来表示一组特别的东西，或特殊状况。

    用一个特定值表示一类状况，这样作很是正确。那么什么状况是不对的那？显然，不能在你的代码中直接使用这样的神奇的原始数值，尤为是不能把它暴露在API中。假设你必须暴露它。请把它包装一下，比方使用#defines定义一个可以让人理解的名字。

阅读下一章节: http://blog.csdn.net/cuibo1123/article/details/39894477

－－－－－－－－－－－－－－－－－－－－－－－－－

英文原名《API Design》
       做者：Matt Gemmell
       原名连接：http://mattgemmell.com/api-design/

中文版由xoneday翻译
       欢迎訪问译者博客：http://blog.xoneday.com
       新浪微博：@xoneday某天

假设这片译文给您带来了帮助。但愿您能经过下载个人APP来支持我：
豆瓣读书：https://itunes.apple.com/cn/app/id695492935
便签夹：https://itunes.apple.com/cn/app/id580552733

           

             便签夹                                        豆瓣读书

＊转载声明：请勿删减做者／译者信息与支持部分的内容，如不接受此条款请勿转载。