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

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了iOS:Cocoa编码规范 -[译]Coding Guidelines for Cocoa相关的知识,希望对你有一定的参考价值。

转载:http://blog.csdn.net/houseq/article/details/27369043

原文地址: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 评价
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(看起来像类名)。

--有的协议包含一些没什么联系的方法(而不是创建多个独立的小协议)。这些协议跟一个类的联系很大,这个类主要体现了这个协议。这种情况下,命名规则为协议名 跟类名字一样 。一个例子是NSObject 协议,这个协议包含一些方法可以查询任何类在父类中的层次位置等。因为NSObject类实现了协议的大部分方法,所以协议可以以类名命名。

--头文件

           怎么命名你的头文件非常重要。因为你的命名表明了类中的内容:

-- 声明一个独立的类/协议: 如果一个类/协议不是一个文件中的一部分,将其声明独立成一个文件,这个文件的名字表明了该类/协议;
-- 声明联系的类/协议: 如果有一些联系的声明(类、协议、分类),将它们声明放到一个文件中,文件的命名根据基础的类、协议、分类;

头文件 声明
NSString.h NSString和NSSMutableString
NSLock.h NSLocking协议、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
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.
         你也可以使用一些计算机行业通用的缩写,例: ASCII、PDF、XML、HTML、URL、RTF、HTTP、TIFF、JPG、PNG、GIF、LZW、ROM、RGB、CMYK、MIDI、FTP
 
 

以上是关于iOS:Cocoa编码规范 -[译]Coding Guidelines for Cocoa的主要内容,如果未能解决你的问题,请参考以下文章

iOS Cocoa - 自定义 uipickerview 或类似

持久 HTTPS 连接 Objective-C iOS Cocoa

iOS Cocoa NSArrayI 长度]:发送到实例的无法识别的选择器

PHP 编码规范

编码规范篇| C#编码规范 代码规范总结,包括命名规范,代码规范 注释规范等

html编码规范