苹果 Cocoa 编码规范(中文版)

2/19目录苹果Cocoa编码规范.....................................................................................................................3代码命名基础...........................................................................................................................3一般性原则.......................................................................................................................3前缀...................................................................................................................................5书写约定...........................................................................................................................5类与协议命名...................................................................................................................5头文件...............................................................................................................................6方法命名...................................................................................................................................8一般性规则.......................................................................................................................8访问方法...........................................................................................................................9委托方法.........................................................................................................................10集合方法.........................................................................................................................11方法参数.........................................................................................................................12私有方法.........................................................................................................................13函数命名.................................................................................................................................14实例变量与数据类型命名.....................................................................................................15实例变量.........................................................................................................................15常量.................................................................................................................................15异常与通知.....................................................................................................................16可接受的缩略语.....................................................................................................................18常见的缩写.....................................................................................................................18常见的略写.....................................................................................................................18框架开发者小贴士与技巧.....................................................................................................19初始化.............................................................................................................................193/19苹果Cocoa编码规范代码命名基础在面向对象软件库的设计过程中，开发人员经常忽视对类，方法，函数，常量以及其他编程接口元素的命名。本节讨论大多数Cocoa接口的一些命名约定。一般性原则清晰性●最好是既清晰又简短，但不要为简短而丧失清晰性代码点评insertObject:atIndex:goodinsert:at:不清晰；要插入什么？“at”表示什么？removeObjectAtIndex:goodremoveObject:这样也不错，因为方法是移除作为参数的对象remove不清晰；要移除什么？●名称通常不缩写，即使名称很长，也要拼写完全代码点评destinationSelectiongooddestSel不清晰setBackgroundColor:goodsetBkgdColor:不清晰你可能会认为某个缩写广为人知，但有可能并非如此，尤其是当你的代码被来自不同文化和语言背景的开发人员所使用时。●然而，你可以使用少数非常常见，历史悠久的缩写。请参考：”可接受的缩略名“一节●避免使用有歧义的API名称，如那些能被理解成多种意思的方法名称4/19代码点评sendPort是发送端口还是返回一个发送端口？displayName是显示一个名称还是返回用户界面中控件的标题？一致性●尽可能使用与Cocoa编程接口命名保持一致的名称。如果你不太确定某个命名的一致性，请浏览一下头文件或参考文档中的范例●在使用多态方法的类中，命名的一致性非常重要。在不同类中实现相同功能的方法应该具有相同的名称代码点评-(int)tag在NSView,NSCell,NSControl中有定义-(void)setStringValue:(NSString*)在许多Cocoaclasses中有定义请参考“方法参数”一节。不要自我指涉●不要名称自我指涉代码点评NSStringokeyNSStringObject自我指涉●掩码（可使用位操作进行组合）和用作通知名称的常量不受该约定限制代码点评NSUnderlineByWordMaskokeyNSTableViewColumnDidMoveNotificationokey5/19前缀前缀是名称的重要组成部分。它们可以区分软件的功能范畴。通常，软件会被打包成一个框架或多个紧密相关的框架（如Foundation和ApplicationKit框架）。前缀可以防止第三方开发者与苹果公司之间的命名冲突（同样也可防止苹果内部不同框架之间的命名冲突）●前缀有规定的格式。它由两到三个大写字符组成，不能使用下划线与子前缀前缀Cocoa框架NSFoundationNSApplicationKitABAddressBookIBInterfaceBuilder●命名class，protocol，structure，函数，常量时使用前缀；命名成员方法时不使用前缀，因为方法已经在它所在类的命名空间种；同理，命名结构体字段时也不使用前缀书写约定在为API元素命名时，请遵循如下一些简单的书写约定●对于包含多个单词的名称，不要使用标点符号作为名称的一部分或作为分隔符（下划线，破折号等）；此外，大写每个单词的首字符并将这些单词连续拼写在一起。请注意以下限制：方法名小写第一个单词的首字符，大写后续所有单词的首字符。方法名不使用前缀。如：fileExistsAtPath:isDirectory:如果方法名以一个广为人知的大写首字母缩略词开头，该规则不适用，如：NSImage中的TIFFRepresentation函数名和常量名使用与其关联类相同的前缀，并且要大写前缀后面所有单词的首字符。如：NSRunAlertPanel，NSCellDisabled避免使用下划线来表示名称的私有属性。苹果公司保留该方式的使用。如果第三方这样使用可能会导致命名冲突，他们可能会在无意中用自己的方法覆盖掉已有的私有方法，这会导致严重的后果。请参考“私有方法”一节以了解私有API的命名约定的建议类与协议命名类名应包含一个明确描述该类（或类的对象）是什么或做什么的名词。类名要有合适的前缀（请参考“前缀”一节）。Foundation及ApplicationKit有很多这样例子，如：NSString,NSData,NSScanner,NSApplication,NSButton以及NSEvent。协议应该根据对方法的行为分组方式来命名。6/19●大多数协议仅组合一组相关的方法，而不关联任何类，这种协议的命名应该使用动名词(ing)，以不与类名混淆。代码点评NSLockinggoodNSLock糟糕，它看起来像类名●有些协议组合一些彼此无关的方法（这样做是避免创建多个独立的小协议）。这