【翻译】苹果官网的命名规范之 Code Naming Basics-General Principles

苹果官方原文链接：General Principles

代码命名基本原则：通用规范

 

代码含义清晰

尽可能将代码写的简洁并且明白是最好的，不过代码清晰度不应该因为过度的简洁而受到影响。例如：

代码	解释
insertObject:atIndex:	命名很好
insert:at:	不太清晰，什么要被插入？at是指什么？
removeObjectAtIndex:	命名很好
removeObject:	命名很好，因为他指明了（要移除）参数中的对象
remove:	不清晰，移除什么？

 

 

 

 

 

 

 

 

 

通常情况下，不要用单词的缩写，即使单词很长。否则代码会变得很难读

代码	解释
destinationSelection	命名很好
destSel	不太清晰.
setBackgroundColor:	命名很好.
setBkgdColor:	不太清晰.

 

 

 

 

 

 

 

你或许认为一些单词的缩写大家都明白，但是不一定。尤其当其他在不同环境下或者不同语言背景吓的开发者看到你写的方法或者函数名称时。当然不排除有些单词缩写已经流行了很长时间并且很通用。你可以继续使用它。

在接口命名中，避免歧义，像一些方法名称可以被解释为多种含义。例如

代码	解释
sendPort	发送一个端口 还是 返回一个发送端口的名称？
displayName	显示一个姓名？还是返回一个用户名称？

 

 

 

 

 

一致性

在整个Cocoa 编码接口中，尽量使用一致的命名。如果你不确定的话，看一看头文件或者参考文档。

当你编写了一个类中需要用到多态的时候，代码一致性显得尤为重要。在不同的类中，命名相同的方法应该做同样的事情。例如

代码	解释
- (NSInteger)tag	在 NSView, NSCell, NSControl.中都有定义
- (void)setStringValue:(NSString *)	在一系列的Cocoa 类中均有定义

 

 

 

 

 

命名不要自我指示。例如 user.username 用 user.name 即可

代码	解释
NSString	可以.
NSStringObject	NSString已经是对象类型，不必要的在加object

 

 

 

 

 

类和协议的命名

一个类的名称应该包含一个能够表明该类所要表达的意思或者功能。类名需要一个适当的前缀。Foundation和Application框架已经有很多例子了，例如：NSString,NSDate,NSScanner,UIButton等

协议（Protocol）应该根据自身所包含的行为来命名

大多数协议都定义了相关联的方法但是并不和一些特定的类有联系。这种协议命名不能和类命名混淆。一种通用的做法就是加 ing

NSLocking  （好的命名） NSLock（不像协议的命名，更像某个类的命名）

头文件

定义相关的类或者协议。在一组相关的类，协议，分类等。把声明放在一个文件中，该文件包含主类、类别或协议的名称。

头文件	定义
NSString.h	NSString 和NSMutableString 类.
NSLock.h	NSLocking 协议and NSLock, NSConditionLock, 和NSRecursiveLock 类.

 

 

 

 

 

包含框架头文件。每一个框架都应该有一个头文件，并且头文件命名和框架命名一致，头文件中包含框架中所有的公开头文件。例如：Foundation.h （Foundation框架），AFNetworking.h

备注：

ambiguity  歧义

interpret 解释