首页 > 代码库 > iOS:Cocoa编码规范 -[译]Coding Guidelines for Cocoa

iOS:Cocoa编码规范 -[译]Coding Guidelines for Cocoa

--原文地址:https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/FrameworkImpl.html

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评价
NSStringokay
NSStringObject自我引用
          常数(看做标记,可以进行位运算)不适用这个规则,例如用作通知名称。
code评价
NSUnderlineByWordMaskokay
NSTableViewColumnDidMoveNotificationokay
--前缀
        前缀在编程接口中是非常重要的一部分。一个软件有不同的功能模块,通常它们封装在一个框架或者相近的框架中。前缀避免了第三方开发者和Apple之间的命名冲突。
--前缀有规定的格式。通常由2/3个大写字母组成,不是用下划线和子前缀。例如:NS、IB、AB。
--使用前缀来命名类、协议、函数、常数,自定义数据类型(typedef structures),不要用前缀来命名方法。方法存在类的命名区域中,不要在这区域里面使用前缀。
--书写规则
         对于由多个单词组成的名字,不要使用标点符号(下划线、破折号等)作为名称部分或作为分隔符。相反每个单词第一个字母大写并且连着写--骆驼风格。注意一下几点:
--对于方法名字,小写字母开头,不要用前缀。一个例外是,方法名称以通用的缩写开头,例如:TIFFRepresentation (NSImage)。
--对于函数和常数,和相关类使用相同的前缀,并且大写第一个字母。例:NSRunAlertPanel、NSCellDisabled。
--避免使用下划线作为前缀意义在于会导致方法名称私有的意思(可以用它做实例变量)。Apple保留使用该规则。但在第三方用可能导致命名冲突,他们会不自觉的重写自己已有的一个私有方法。参考“私有方法”章节。
--类和协议名称
         一个类的名称应该包含一个名词,清楚地表明的类(或类的对象)作用或者意义。名称应该有一个适当的前缀(参考“前缀”小节)。在框架中类名的例子比比皆是:NSString,NSDate,nsscanner,NSApplication,UIApplication,NSButton, and UIButton。
        协议的命名应该根据使用协议的相应类行为命名。
--大多数协议包含的相关方法,不与任何特定的类关联。这种协议的应该命名为使协议与类不能混淆。一个通常的规则是用动名词(...ing)。对比NSLocking 、NSLock(看起来像类名)。
--有的协议包含一些没什么联系的方法(而不是创建多个独立的小协议)。这些协议跟一个类的联系很大,这个类主要体现了这个协议。这种情况下,命名规则为协议名跟类名字一样。一个例子是NSObject 协议,这个协议包含一些方法可以查询任何类在父类中的层次位置等。因为NSObject类实现了协议的大部分方法,所以协议可以以类名命名。
--头文件
           怎么命名你的头文件非常重要。因为你的命名表明了类中的内容:
--声明一个独立的类/协议:如果一个类/协议不是一个文件中的一部分,将其声明独立成一个文件,这个文件的名字表明了该类/协议;
--声明联系的类/协议:如果有一些联系的声明(类、协议、分类),将它们声明放到一个文件中,文件的命名根据基础的类、协议、分类;
头文件声明
NSString.hNSString和NSSMutableString
NSLock.hNSLocking协议、NSLock、NSConditionLock、NSRecursive类
--包含框架的头文件:所有的框架都有一个头文件,以框架命名,包含框架里所有公开的头文件。例Foundation.h-- Foundation.framwork。
--为别的框架中类增加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
----不要使用"and"去连接多个参数的关键词(对象属性名)
- (int)runModalForDirectory:(NSString *)path file:(NSString *) name types:(NSArray *)fileTypes;right
- (int)runModalForDirectory:(NSString *)path andFile:(NSString *)name andTypes:(NSArray *)fileTypes;wrong
       尽管在这个例子中and看起来还不错,但是当方法中有许多参数的时候,再用and就不行了。
----如果方法包含着俩个分开的动作,用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
----可以使用情态动词(动词前面“can”、“should”、“will”等)进一步说明属性意思,但不要使用‘do‘或‘does‘。
- (void)setCanHide:(BOOL)flag;Y
- (BOOL)canHide;Y
- (void)setShouldCloseDocument:(BOOL)flag;Y
- (BOOL)shouldCloseDocument;Y
- (void)setDoesAcceptGlyphInfo:(BOOL)flag;N
- (BOOL)doesAcceptGlyphInfo;N
----当使用get这个词时,只有当方法间接返回多个对象/值。- (void)getLineDash:(float *)pattern count:(int *)count phase:(float *)phase;  注意,这种形式的方法,其中的引用型参数应该能接收NULL,因为方法调用者可能并不需要多个返回值。
--代理方法
      代理方法是那些当发生特定事件对象使用它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.)
        以上说的集合方法的规则在NSWindow类中都有例子:
- (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框架类的子类,你不知道你的私有方法是否无意中重写方法里同名称的私有方法。
         在Cocoa框架中命名大多数私有的方法用下划线前缀开头(例如,_foodata),标记方法为私有。对于这条规则,有两个建议:
-----对于你自己的私有方法,不要使用下划线前缀。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”。

----你可以在参数中更自由的使用缩写。例如:“imageRep”, “col” (for “column”),“obj”, and “otherWin”
缩写意义
alloc Allocate
altAlternate
app应用程序,例, NSApp全局应用程序对象。 “application” 全拼在delegate方法、通知中等
calcCalculate.
deallocDeallocate.
funcFunction.
horizHorizontal.
infoInformation
initInitialize
max/minMaximum/Minimum.
msgMessage
nibInterface Builder archive.
pboardPasteboard (but only in constants
rectRectangle.
RepRepresentation (used in class name such as NSBitmapImageRep
tempTemporary.
vertVertical.
         你也可以使用一些计算机行业通用的缩写,例:ASCII、PDF、XML、HTML、URL、RTF、HTTP、TIFF、JPG、PNG、GIF、LZW、ROM、RGB、CMYK、MIDI、FTP