Cocoa编码规范

Posted 2021-04-30 iOS大全

英文：《Coding Guidelines for Cocoa》

译文：葛布林大帝

链接：http://www.cnblogs.com/yangfaxian/p/4673894.html

简介：

本文整理自Apple文档《Coding Guidelines for Cocoa》。这份文档原意是给Cocoa框架、插件及公共API开发者提供一些编码指导，实质上相当于Apple内部的编码规范。在多人协作时，一份统一的代码规范大大减少开发者之间的沟通成本，极力推荐。

目录：

一、代码命名基础

二、方法

三、函数

四、Property及其他

五、缩写

一、代码命名基础

1.通用原则

1.1 清晰

尽量清晰又简洁，无法两全时清晰更重要

通常不应缩写名称，即使方法名很长也应完整拼写

你可能认为某个缩写众所周知，但其实未必，特别是你周围的开发者语言文化背景不同时

有一些历史悠久的缩写还是可以使用的，详见第五章

API命名避免歧义，例如一个方法名有多种理解

1.2 一致

尽力保持Cocoa编程接口命名一致

如果有疑惑，请浏览当前头文件或者参考文档

当某个类的方法使用了多态时，一致性尤其重要

不同类里，功能相同的方法命名也应相同

1.3 避免自引用（self Reference）

命名不应自引用，这里的自引用指的是在词尾引用自身

Mask与Notification忽略此规则

2.前缀

前缀是编程接口命名的重要部分，它们区分了软件的不同功能区域：

• 前缀可以防止第三方开发者与Apple的命名冲突

• 同样可以防止Apple内部的命名冲突

• 前缀有指定格式

• 它由二到三个大写字母组成，不使用下划线和子前缀

• 命名类、协议、函数、常量和typedef结构体时使用前缀

• 方法名不使用前缀（因为它存在于特定类的命名空间中）

• 结构体字段不使用前缀

3.书写约定

在命名API元素时， 使用驼峰命名法（如runTheWordsTogether），并注意以下书写约定：

方法名

• 小写第一个字母，大写之后所有单词的首字母，不使用前缀

• 如果方法名以一个众所周知的大写缩略词开始，该规则不适用

如TIFFRepresentation (NSImage)

fileExistsAtPath:isDirectory:

函数及常量名

• 使用与其关联类相同的前缀，并大写首字母

NSRunAlertPanel

NSCellDisabled

标点符号

• 由多个单词组成的名称，别使用标点符号作为名称的一部分

• 分隔符（下划线、破折号等）也不能使用

• 避免使用下划线作为私有方法的前缀，Apple保留这一方式的使用

• 强行使用可能会导致命名冲突，即Apple已有的方法被覆盖，这会导致灾难性后果

• 实例变量使用下划线作为前缀还是允许的

  
  

4.class与protocol命名

class

• class的名称应该包含一个名词，用以表明这个类是什么（或者做了什么），并拥有合适的前缀

• 如NSString、NSDate、NSScanner、UIApplication、UIButton

• 
  

不关联class的protocol

• 大多数protocol聚集了一堆相关方法，并不关联class

• 这种protocol使用ing形式以和class区分开来

关联class的protocol

• 一些protoco聚集了一堆无关方法，并试图与某个class关联在一起，由这个class来主导

• 这种protocol与class同名

• 如NSObject protocol

• 
  

5.头文件

头文件的命名极其重要，因为它可以指出头文件包含的内容：

• 声明一个孤立的class或protocol

• 将声明放入单独的文件

• 使头文件名与声明的class/protocol相同

• 声明关联的class或protocol
  

• 将关联的声明（class/category/protocol）放入同一个头文件

• 头文件名与主要的class/category/protocol相同

• Framework头文件
  

• 每个framework都应该有一个同名头文件

• Include了框架内其他所有头文件

• 添加API到另一个framework
  

• 如果要在一个framework中为另一个framework的class catetgory添加方法，加上单词“Additions”

• 如Application Kit的NSBundleAdditions.h 文件

• 关联的函数、数据类型

• 如果你有一组关联的函数、常量、结构体或其他数据类型，将它们放到一个名字合适的头文件中

• 如Application Kit的NSGraphics.h

• 
  

二、方法

1.通用原则

• 以小写字母开始，之后单词的首字母大写

• 以众所周知的缩写开始可以大写，如TIFF、PDF

• 私有方法可以加前缀

• 如果方法代表对象接收的动作，以动词开始

• 不要使用 do 或 does 作为名字的一部分，因为助动词在这里很少有实际意义

• 同样的，也别在动词之前使用副词和形容词

  
  

- (void)invokeWithTarget:(id)target;

- (void)selectTabViewItem:(NSTabViewItem *)tabViewItem

• 
  

• 如果方法返回接收者的属性，以 接收者 + 接收的属性 命名

• 除非间接返回多个值，否则不要使用 get 单词（为了与accessor methods区分）

在所有参数之前使用关键字

确保参数之前的关键字充分描述了参数

创建自定义 init 方法时，记得指明关联的元素

不要使用 and 来连接作为接收者属性的关键字

• 虽然下面的例子使用 and 看似不错，但是一旦参数非常多时就容易出现问题

• 
  

除非方法描述了两个独立的操作，才使用 and 来连接它们

2.getter和setter方法（Accessor Methods）

如果property表示为名词，格式如下

- (type)noun;

- (void)setNoun:(type)aNoun;

- (BOOL)isAdjective;

- (NSString *)title;

- (void)setTitle:(NSString *)aTitle;

如果property表示为形容词，格式如下

- (BOOL)isAdjective;

- (void)setAdjective:(BOOL)flag;

- (BOOL)isEditable;

- (void)setEditable:(BOOL)flag;

如果property表示为动词，格式如下（动词用一般现在时）

- (BOOL)verbObject;

- (void)setVerbObject:(BOOL)flag;

- (BOOL)showsAlpha;

- (void)setShowsAlpha:(BOOL)flag;

你可能使用情态动词（can、should、will等）来增加可读性，不过不要使用 do或 does

只有方法需要间接返回多个值的情况下才使用 get

像这种接收多个参数的方法应该能够传入nil，因为调用者未必对每个参数都感兴趣

3.Delegate方法

以发送消息的对象开始

省略了前缀的类名和首字母小写

- (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row;

- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;

以发送消息的对象开始的规则不适用下列两种情况

只有一个sender参数的方法

- (BOOL)applicationOpenUntitledFile:(NSApplication *)sender; 以上是关于Cocoa编码规范的主要内容，如果未能解决你的问题，请参考以下文章 iOS:Cocoa编码规范 -[译]Coding Guidelines for Cocoa 递进迭代敏捷 iOS-常见编程规范汇总 （Cocoa 错误 3840。）”（JSON 文本没有以数组或对象开头，并且允许未设置片段的选项。） php Yoast SEO规范输出的代码片段 php Yoast SEO规范输出的代码片段