iOS:Cocoa编码规范 -[译]Coding Guidelines for Cocoa
转载:http://blog.csdn.net/houseq/article/details/27369043
Cocoa编码规范
--前言
用公共API开发一个Cocoa框架，插件，或其他可执行目标，里面的命名编写和规范不同于一般应用程序的开发。因为你开发出来东西是给开发者用的看的， 并且他们不熟悉你的编程接口。这个时候API的命名约定就派上用场了，因为它使你的写的接口清楚明确。本文档里还包括开发框架中一些特殊的/重要的编程技 术，例如：版本控制，二进制兼容性，错误处理，和内存管理。本文档包含俩部分内容：Cocoa命名规范、一些框架的编程实践。
--文档组织
本文档内容分类俩大部分：第一部分是主要内容，为编程接口的命名规范。这些规范(有一些小的例外)也是Apple开发自己框架所用的规范。这些命名规范 具体体现在以下几个方面：“基本代码命名”、“方法命名”、“函数命名”、“属性和数据类型命名”、“通用的缩写和简称”。 第二块部分讨论框架编程方面：“使用框架中的一些技巧和技术”。
注：本文章只翻译前一部分内容，即：
Cocoa命名规范
========================章节分割线==============================
--基本命名规则
在面对对象软件库开发中，一个经常被忽视的问题是：类、方法、函数、常数等编程接口的命名问题。这一章主要讨论Cocoa接口中常用代码的命名规范。
--一般规则
--明确
代码越简洁越明确越好，但是不能因为简洁而导致语义不明确：
| 代码 | 评价 |
| insertObject: atIndex: | 好 |
| insert:at: | 不明确，什么被插入？at指什么 |
| removeObjectAtIndex: | 好 |
| removeObject: | 好，没有之前讨论的那些问题 |
| remove: | 不明确，什么被移除了 |
通常，不要缩写对象的名称。即使它们很长，也全拼：
| 代码 | 评价 |
| destinationSelection | 好 |
| destSel | 不明确 |
| setBackgroundColor: | 好 |
| setBkgdColor: | 不明确 |
--你可能认为某些缩写是众所周知的。但凡是无绝对，尤其是当开发者和你文化、语言背景不一样，看这些缩写就可能产生歧义。
--当然，一些公认的通用的缩写，还是可以用。参考“通用的缩写”章节
在API的命名上避免歧义，例如方法的名字可以有多个解释：
| code | 评价 |
| sendPort | 是发送端口还是返回端口 |
| displayName | 它是显示一个名字还是在用户界面返回消息发送者的标题 |
--一致性
始终使用Cocoa 编程接口的名字。如果你不太确定，查看已有的头文件和参考文档。
一致性非常重要，当你有个实现多态方法的类。不同类中处理同一个任务的方法应该拥有同样的名称。
| code | 评价 |
| - (NSInteger)tag | 在 NSView, NSCell, NSControl类中都要定义 |
--不要自我引用(Self Reference)
命名不应该自我重复。
| code | 评价 |
| NSString | okay |
| NSStringObject | 自我引用 |
| code | 评价 |
| NSUnderlineByWordMask | okay |
| NSTableViewColumnDidMoveNotification | okay |
--前缀
前缀在编程接口中是非常重要的一部分。一个软件有不同的功能模块，通常它们封装在一个框架或者相近的框架中。前缀避免了第三方开发者和Apple之间的命名冲突。--前缀有规定的格式。通常由2/3个大写字母组成，不是用下划线和子前缀。例如：NS、IB、AB。
--使用前缀来命名类、协议、函数、常数，自定义数据类型(typedef structures)，不要用前缀来命名方法。方法存在类的命名区域中，不要在这区域里面使用前缀。
--书写规则
对于由多个单词组成的名字，不要使用标点符号(下划线、破折号等)作为名称部分或作为分隔符。相反每个单词第一个字母大写并且连着写-- 骆驼风格 。注意一下几点：
--对于方法名字，小写字母开头，不要用前缀。一个例外是，方法名称以通用的缩写开头，例如：TIFFRepresentation (NSImage)。
--对于 函数和常数，和相关类使用相同的前缀，并且大写第一个字母 。例：NSRunAlertPanel、NSCellDisabled。
--避免使用下划线作为前缀意义在于会导致方法名称私有的意思（可以用它做实例变量）。Apple保留使用该规则。但在第三方用可能导致命名冲突，他们会不自觉的重写自己已有的一个私有方法。参考“私有方法”章节。
--类和协议名称
一个类的名称应该 包含一个名词，清楚地表明的类（或类的对象）作用或者意义
。名称应该有一个适当的前缀（参考“前缀”小节）。在框架中类名的例子比比皆是：NSString，NSDate，nsscanner，NSApplication，UIApplication，NSButton, and UIButton。
协议的命名应该根据使用协议的相应类行为命名。
--大多数协议包含的相关方法，不与任何特定的类关联。这种协议的应该命名为使协议与类不能混淆。一个通常的规则是 用动名词(...ing )。对比NSLocking 、NSLock(看起来像类名)。
--头文件
怎么命名你的头文件非常重要。因为你的命名表明了类中的内容：
-- 声明一个独立的类/协议：
如果一个类/协议不是一个文件中的一部分，将其声明独立成一个文件，这个文件的名字表明了该类/协议；
-- 声明联系的类/协议：
如果有一些联系的声明（类、协议、分类），将它们声明放到一个文件中，文件的命名根据基础的类、协议、分类；
| 头文件 | 声明 |
| NSString.h | NSString和NSSMutableString |
| NSLock.h | NSLocking协议、NSLock、NSConditionLock、NSRecursive类 |
--为别的框架中类增加API： 如果你在一个框架中声明的方法，是另一个框架中类的分类，名字为原来类的名字拼接上“Additions”。一个例子为Applicatiion kit 的NSBuddleAdditions.h头文件。
--相联系的函数和数据类型：如果你有一些相联系的函数、常数、结构体等其他数据类型，将它们放到合适命名的头文件中。例如NSGraphics.h(Applicatiion kit )。
=========================================章节分割线=========================================
--方法命名
方法在编程接口中非常常见，所以命名方法要重视。这章主要讨论方法命名的以下几个方面：
--基本规则
当为方法命名时，要记住以下几点：
----方法名小写开头，之后每个单词首字母大写（Camel-Case），不要用前缀；
有俩种情况例外。如果方法用到了众所周知的缩写(例如TIFF或PDF) ；你可能使用前缀去统一定义私有方法，参考“私有方法”小节。
----如果方法代表对象某个动作，方法名用动词开头；
例如：- (void)invokeWithTarget:(id)target;
不要使用"do"或"does"这样的词做名字一部分，因为这些辅助动词没什么意义，同时不要在动词前使用副词或形容词。
-----如果方法返回的是消息发送者(对象)的属性，用属性命名方法。"get"这个词不需要，除非有多个间接返回的值。 可以参考“存取器方法”小节。
| - (NSSize)cellSize; | 正确 |
| - (NSSize)calcCellSize; | 错误 |
| - (NSSize)getCellSize; | 错误 |
----在所有的参数前使用关键词
| - (void)sendAction:(SEL)aSelector toObject:(id)anObject forAllCells:(BOOL)flag; | 正确 |
| - (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag; | 错误 |
| - (id)viewWithTag:(NSInteger)aTag; | 正确 |
| - (id)taggedView:(int)aTag; | 错误 |
| - (id)initWithFrame:(CGRect)frameRect; | UIView |
| - (id)initWithFrame:(NSRect)frameRect mode:(int)aMode cellClass:(Class)factoryId numberOfRows:(int)rowsHigh numberOfColumns:(int)colsWide; |
NSMatrix, a subclass of NSView |
| - (int)runModalForDirectory:(NSString *)path file:(NSString *) name types:(NSArray *)fileTypes; | right |
| - (int)runModalForDirectory:(NSString *)path andFile:(NSString *)name andTypes:(NSArray *)fileTypes; | wrong |
----如果方法包含着俩个分开的动作，用and去连接它们 ；例：- (BOOL)openFile:(NSString *)fullPath withApplication:(NSString *)appName andDeactivate:(BOOL)flag;
--存取器方法
存取器放方法是指那些读/写对象属性的方法，根据属性意义的不同，它们有不同的通用格式。( 备注：不同格式代表不同对应实例变量的写法，存取器方法形式就是intanceVariables 和 setIntanceVariables俩种形式 )
----如果属性表示的是名词意思， 格式如： - (type)noun; - (void)setNoun:(type)aNoun;
----如果属性表示的是形容词意思， 格式如： - (BOOL)isAdjective; - (void)setAdjective:(BOOL)flag; (注意type是BOOL)
例：- (BOOL)isEditable; - (void)setEditable:(BOOL)flag;
----如果属性表示的是动词意思 ，
格式如： (BOOL)verbObject; - (void)setVerbObject:(BOOL)flag; (注意type为BOOL)
例： - (BOOL)showsAlpha; - (void)setShowsAlpha:(BOOL)flag; 动词是现在时；
| - (void)setAcceptsGlyphInfo:(BOOL)flag; | right |
| - (BOOL)acceptsGlyphInfo; | right |
| - (void)setGlyphInfoAccepted:(BOOL)flag; | wrong |
| - (BOOL)glyphInfoAccepted; | wrong |
| - (void)setCanHide:(BOOL)flag; | Y |
| - (BOOL)canHide; | Y |
| - (void)setShouldCloseDocument:(BOOL)flag; | Y |
| - (BOOL)shouldCloseDocument; | Y |
| - (void)setDoesAcceptGlyphInfo:(BOOL)flag; | N |
| - (BOOL)doesAcceptGlyphInfo; | N |
--代理方法
代理方法是那些当发生特定事件对象使用它delegate调用的方法(如果delegate实现了它)，它们有着特定的格式，这些格式也适用于对象的datesource方法。
----名字的开头指明发消息的对象类型。 例如：- (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row; - (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename; 类名省略了它的前缀 并且小写开头。
---- 如果方法只有一个参数，格式为：冒号+类名(调用代理的对象)+sender ；例：- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;
---- 一个例外是方法用来发送通知，如果这样的话，方法参数为通知对象； 例：- (void)windowDidChangeScreen:(NSNotification *)notification;
-----命名中使用"did"或"will"这类词，告诉delegate某些事情已经发生或将要发生； 例：- (void)browserDidScroll:(NSBrowser *)sender;
---- 虽然你可以在命名中是使用"did"或"will"这类词，告诉delegate去做某些事情，但有时“should”更合适； 例：- (BOOL)windowShouldClose:(id)sender;
--集合方法(Collection Method)
要管理对象(每一个叫做对象的元素)的集合，命名方法以下格式：
- (void)addElement:(elementType)anObj;
- (void)removeElement:(elementType)anObj;
- (NSArray *)elements;
- (void)addLayoutManager:(NSLayoutManager *)obj;
- (void)removeLayoutManager:(NSLayoutManager *)obj;
- (NSArray *)layoutManagers;
以下是一些重要、有用的的规格：
--如果集合没有顺序，返回NSSet比NSArray更好；
--如果在集合中插入元素，位置很重要的话，使用以下的格式比前面提到的更好 ：
例如： - (void)insertLayoutManager:(NSLayoutManager *)obj atIndex:(int)index; - (void)removeLayoutManagerAtIndex:(int)index;
以下一些实现细节要注意：
----这些方法通常暗含插入对象的拥有权(ownership)的管理，所以添加/插入元素的时候retain它们，移除的时候remove它们；
---- 如果插入对象想保持它原来的持有的对象，通常对该对象的setter方法不用retain ，例如insertLayoutManager:atIndex: method方法。NSLayoutManager类在以下的方法中同样这样处理：- (void)setTextStorage:(NSTextStorage *)textStorage; - (NSTextStorage *)textStorage; 通常你不用调用setTextStorage方法，但是你可能需要重写它。
----(这段难理解，上面属于个人见解，参考原文：If the inserted objects need to have a pointer back to the main object, you do this (typically) with a set...method that sets the back pointer but does not retain. In the case of the insertLayoutManager:atIndex: method, the NSLayoutManager class does this in these methods: - (void)setTextStorage:(NSTextStorage *)textStorage; - (NSTextStorage *)textStorage; You would normally not call setTextStorage: directly, but might want to override it.)
| - (void)addChildWindow:(NSWindow *)childWin ordered:(NSWindowOrderingMode)place; |
| - (void)removeChildWindow:(NSWindow *)childWin; |
| - (NSArray *)childWindows; |
| - (NSWindow *)parentWindow; |
| - (void)setParentWindow:(NSWindow *)window; |
----方法参数
在命名方法参数时候有几个基本规则：
----参数的名字也是骆驼风格
----不要使用“pointer”或"ptr"这些词，参数的类型比参数的名字更能说明它是否是指针。
----避免一俩个字母做参数的名字
----避免缩写，参数名不差多这几个字母。
一般来讲，以下的一些方法中的关键词通常跟固定的参数搭配：
...action:(SEL)aSelector
...alignment:(int)mode
...atIndex:(int)index
...content:(NSRect)aRect
...doubleValue:(double)aDouble
...floatValue:(float)aFloat
...font:(NSFont *)fontObj
...frame:(NSRect)frameRect
...intValue:(int)anInt
...keyEquivalent:(NSString *)charCode
...length:(int)numBytes
...point:(NSPoint)aPoint
...stringValue:(NSString *)aString
...tag:(int)anInt
...target:(id)anObject
...title:(NSString *)aString
----私有方法
在大多数情况下，私有的方法名称一般跟公共方法的名称都遵循同样的规则作为。然而，还有一个普遍的规则是给私有方法一个前缀，所以很容易区分他们跟公共方法。
即使遵循这些规则，私有方法名称还是可以引起一些特殊问题。当你你编写的Cocoa框架类的子类，你不知道你的私有方法是否无意中重写方法里同名称的私有方法。
-----对于你自己的私有方法，不要使用下划线前缀。Apple约定了这条规则；
-----如果是一个大cocoa框架类（如NSView）的子类，你要绝对确保你的私有的方法不同于父类的方法，您可以通过添 加你自己独有的前缀来区分。前缀应尽可能的唯一的，也许是一个基于在你公司或项目的形式”xx_”。所以如果你的项目被称为Byte Flogger，前缀可以是BF_addobject；
虽然之前建议用前缀给私有方法命名，这看起来跟之前说的规则矛盾。但这块情况特殊，我们必须确保子类无意间重写父类的私有方法。
=========================================章节分割线=========================================
---函数命名
Objective-c中实现一个功能可以通过函数和方法。当你的对象是单实例或者处理一个子功能时候，更适合用函数。
函数命名有几下基本原则：
----函数名类似方法名，但有一些例外： 它们用你在类/常数中的前缀开头，并且前缀后的首字母大写。
----许多函数名字已动词开头，描述函数实现的功能：NSHighlightRect NSDeallocateObject
----函数如果是查询一些属性，命名有一些特别的规定：
1.如果函数返回第一个参数的属性，省略动词 ：unsigned int NSEventMaskFromType(NSEventType type) float NSHeight(NSRect aRect)
2.如果函数返回值是指针，使用"Get" ：const char *NSGetSizeAndAlignment(const char *typePtr, unsigned int *sizep, unsigned int *alignp)
3.如果函数返回值是布尔型，函数名用变化的(inflected)动词开头 ：BOOL NSDecimalIsNotANumber(const NSDecimal *decimal)
=========================================章节分割线=========================================
--属性和数据类型命名
这部分讲命名属性、实例变量、常数、通知、异常。
----属性和实例变量命名
因为属性和存取器方法的对应性质( get方法和set后那部分名称即是属性名字，对应实例变量 )，所以对于属性的命名基本类似存取器方法的名字，参考"存取器方法"小节。
---- 如果属性是名称/动词意思，格式是：@property (…) type nounOrVerb
例：@property (strong) NSString *title; @property (assign) BOOL showsAlpha;
----- 如果属性是形容词意思，属性名称省略"is"前缀，并且指定存取器get方法的命名 。例如：@property (assign, getter=isEditable) BOOL editable;
在许多情况，当你声明一个了属性， 你同时也确定(synthesize)了相应的实例变量 。
@implementation MyClass {
BOOL _showsTitle;
}
如果你想用某实例变量对应某个属性，在@synthesize中说明：@implementation MyClass @synthesize showsTitle=_showsTitle;当添加实例变量的时候，有以下几条规则：
-----避免显示的声明公共的实例变量。开发者只会关心对象的接口，不关心实现的细节。通过声明属性和相应的(synthesizing)实例变量，避免显示声明实例变量。
-----如果需要声明实例变量，用@private 或者 @protected声明。如要继承的实例变量用@protected声明。
-----如果一个实例变量是实例的访问属性(accessible attribute)，确保你已经写了相应的存取器方法 。
--常数
常数的命名规则跟常数是怎么产生的息息相关。
--枚举常数
---- 对于有取值相联系的常数集合，使用枚举(说什么情况使用枚举，跟命名没关系)
----枚举常数和typedef后面枚举名的命名跟函数的命名规则类似
，参考"函数命名"小节。例：
typedef enum _NSMatrixMode {
NSRadioModeMatrix = 0,
NSHighlightModeMatrix = 1,
NSListModeMatrix = 2,
NSTrackModeMatrix = 3
} NSMatrixMode;
注意上文中_NSMatrixMode 在typedef中没有用。
----你也可以使用不命名的枚举，比如 位掩码(bit masks)， 例如：
enum {
NSBorderlessWindowMask = 0,
NSTitledWindowMask = 1 << 0,
NSClosableWindowMask = 1 << 1,
NSMiniaturizableWindowMask = 1 << 2,
NSResizableWindowMask = 1 << 3
};
--const修饰的常数
-----使用const去创建浮点型常量。可以创建整形常量，如果各整形常量之间没有什么联系，否则，使用枚举。
----const修饰的常数命名规则，举例说明： const float NSLightGray; 命名规则类似函数，参考"函数命名"
小节。
--其他类型常数
----通常
不使用#define预编译命令去创建常数
。像上文说的，
整形常数用枚举，浮点型常数用const修饰
。
----使用大写字母符号让编译器决定某段代码是否编译。例如：#ifdef DEBUG
----注意由编译器定义的宏，有前后各俩个下划线 。例如：__MACH__；
---- 定义字
符串常数 ，例如作方法名或字典的key等，你要确保编译器识别字符串常数(编译语法检查)。Cocoa提供了许多字符串常量例子，如： APPKIT_EXTERN NSString *NSPrintCopies ; 字符串的值被指定了常量（注意APPKIT_EXTERN 宏在Objective-C中的像extern声明的作用）
--通知和异常
通知和异常的命名规则基本相同，但它们有各自特点。
--通知
如果一个类有delegate，许多通知都会被delegate接收通过delegate方法。 这些通知的名称应该反应相应的delegate方法 。例如，一个全局的NSApplication类对象自动注册去接收applicationDidBecomeActive消息，当应用程序发送 NSApplicationDidBecomeActiveNotification.消息的时候。通知通过全局的字符串对象定义， 格式如下：[Name of associated class] + [Did | Will] + [UniquePartOfName] + Notification； 例：
NSApplicationDidBecomeActiveNotification NSWindowDidMiniaturizeNotification NSTextViewDidChangeSelectionNotification NSColorPanelColorDidChangeNotification
--异常
尽管你可以为了一些目的自由的使用异常(由NSException类和相关函数提供)，Cocoa将编程中出现错误，例如数组越界，看做异常。 Cocoa不使用异常去处理常规的、预料的错误情况，例如，返回值为nil、NULL、NO或一些错误代码。详细参考《Error Handling Programming Guide》。
异常通过全局的字符串对象定义，格式如下 ：[Prefix] + [UniquePartOfName] + Exception； 其中unique part of the name是由单词组合而成，每个首字母大写。例如：
NSColorListIOException NSColorListNotEditableException NSDraggingException NSFontUnavailableException NSIllegalSelectorException
=========================================章节分割线=========================================
--通用的缩写和简称
通常你不用缩写你的命名，当你编写接口时候。参考"基本命名规则"章节。然而，下面所列举的缩写都是众所周知的，你可以继续使用它们。有以下几点需要注意：
----缩写的替代格式使用在标准C语音库中被允许。例如：“alloc” and “getc”。
| 缩写 | 意义 |
| alloc | Allocate |
| alt | Alternate |
| app | 应用程序，例, NSApp全局应用程序对象。 “application” 全拼在delegate方法、通知中等 |
| calc | Calculate. |
| dealloc | Deallocate. |
| func | Function. |
| horiz | Horizontal. |
| info | Information |
| init | Initialize |
| max/min | Maximum/Minimum. |
| msg | Message |
| nib | Interface Builder archive. |
| pboard | Pasteboard (but only in constants |
| rect | Rectangle. |
| Rep | Representation (used in class name such as NSBitmapImageRep |
| temp | Temporary. |
| vert | Vertical. |
