2.1. 代码命名基础

一般原则

清晰性

  • 最好是既清晰又简短,但不要为简短而丧失清晰性

代码

点评

insertObject: atIndex:

好

insert: at:

不清晰：要插入什么？“at”表示什么？

removeObjectAtIndex:

好

removeObject:

这样也不错,因为方法是移除作为参数的对象

remove:

不清晰：要移除什么?

  • 名称通常不缩写,即使名称很长,也要拼写完全。（使用US英文，禁止拼音）

代码

点评

destinationSelection:

好

destSel:

不好

setBackgroundColor:

好

setBkgdColor:

不好

你可能会认为某个缩写广为人知,但有可能并非如此,尤其是当你的代码被来自不同文化和语言背景的开发人员所使用时。

  • 然而你可以使用少数非常常见,历史悠久的缩写。请参考可接受的缩略名一节

  • 避免使用有歧义的 API 名称,如那些能被理解成多种意思的方法名称

代码

点评

sendPort:

是发送端口还是返回一个发送端口？

displayName:

是显示一个名称还是返回用户界面中控件的标题？

一致性

  • 尽可能使用与Cocoa编程接口命名保持一致的名称。如果你不太确定某个命名的一致性，请浏览一下头文件或参考文档中的范例。

  • 在使用多态方法的类中，命名的一致性非常重要，在不同类中实现相同功能的方法应该具有相同的名称。

代码

点评

- (int) tag

在 NSView，NSCell，NSControl 中有定义

- (void)setStringValue:(NSString *)

在许多Cocoa类中有定义

更多请看方法参数

前缀

通常，软件会被打包成一个框架或多个紧密相关的框架(如 Foundation 和 Application Kit 框架)。但由于Cocoa没有像C++一样的命名空间概念，所以我们只能用前缀来区分软件的功能范畴，防止命名冲突。

  • 类名和常量应该始终使用三个字母的前缀（例如 NYT），因为两个字母的前缀是苹果SDK先使用的，但 Core Data 实体名称可以省略。为了代码清晰，常量应该使用相关类的名字作为前缀并使用驼峰命名法。

下面是常见的苹果官方的前缀

前缀

Cocoa 框架

NS

Foundation

NS

Application Kit

AB

Address Book

IB

Interface Builder

比如在我们的APP中蓝牙模块（Bluetooth low energy）管理类

@interface BLEManager : NSObject
@property (assign) BLEDeviceType deviceType;
@end

书写约定

在为 API 元素命名时,请遵循如下一些简单的书写约定

  • 对于包含多个单词的名称,不要使用标点符号作为名称的一部分或作为分隔符(下划线,破折号等); 此外,大写每个单词的首字符并将这些单词连续拼写在一起。请注意以下限制:

    • 方法名小写第一个单词的首字符,大写后续所有单词的首字符。方法名不使用前缀。如: fileExistsAtPath:isDirectory: 如果方法名以一个广为人知的大写首字母缩略词开头,该规则不适 用,如:NSImage 中的 TIFFRepresentation

    • 函数名和常量名使用与其关联类相同的前缀,并且要大写前缀后面所有单词的首字符。如: NSRunAlertPanel，NSCellDisabled

    • 避免使用下划线来表示名称的私有属性。苹果公司保留该方式的使用。如果第三方这样使用可能会导致命名冲突,他们可能会在无意中用自己的方法覆盖掉已有的私有方法,这会导致严重的后 果。请参考私有方法一节以了解私有 API 的命名约定的建议

类与协议命名

类名应包含一个明确描述该类(或类的对象)是什么或做什么的名词。类名要有合适的前缀(请参考前缀 一节)。Foundation 及 Application Kit 有很多这样例子,如:NSString, NSData, NSScanner, NSApplication, NSButton 以及 UIButton。

协议应该根据对方法的行为分组方式来命名。

  • 大多数协议仅组合一组相关的方法,而不关联任何类,这种协议的命名应该使用动名词(ing),以不与 类名混淆。

代码

点评

NSLocking

good

NSLock

糟糕,它看起来像类名

  • 有些协议组合一些彼此无关的方法(这样做是避免创建多个独立的小协议)。这样的协议倾向于与某个类关联在一起,该类是协议的主要体现者。在这种情形,我们约定协议的名称与该类同名。NSObject协议就是这样一个例子。这个协议组合一组彼此无关的方法,有用于查询对象在其类层次中位置的方法,有使之能调用特殊方法的方法以及用于增减引用计数的方法。由于 NSObject 是这些方法的主要体现者,所以我们用类的名称命名这个协议。

头文件

头文件的命名方式很重要,我们可以根据其命名知晓头文件的内容。

  • 声明孤立的类或协议:将孤立的类或协议声明放置在单独的头文件中,该头文件名称与类或协议同名

头文件

声明

NSApplication.h

NSApplication 类

  • 声明相关联的类或协议:将相关联的声明(类,类别及协议) 放置在一个头文件中,该头文件名称与主要的类,类别,协议的名字相同。

头文件

声明

NSString.h

NSString 和 NSMutableString 类

NSLock.h

NSLocking 协议和 NSLock, NSConditionLock, NSRecursiveLock 类

  • 包含框架头文件:每个框架应该包含一个与框架同名的头文件,该头文件包含该框架所有公开的头文件。

头文件

声明

Foundation.h

Foundation.framework

  • 为已有框架中的某个类扩展 API:如果要在一个框架中声明属于另一个框架某个类的范畴类的方法, 该头文件的命名形式为:原类名+“Additions”。如 Application Kit 中的 NSBundleAdditions.h

  • 相关联的函数与数据类型:将相联的函数,常量,结构体以及其他数据类型放置到一个头文件中,并以合适的名字命名。如 Application Kit 中的 NSGraphics.h

Previous2. 代码命名规范Next2.2. 方法(Method)命名

Last updated