cocoa 编程指南(一)——代码命名基础

面前对象软件库的设计经常被忽略的一个方便是类,方法,函数,常量以及编程接口的其他元素的命名。本章节讨论Cocoa界面的大多数项目通用的几个命名约定。

一般原则

明晰

尽可能清晰简洁是很好的,但是清晰度不应该由于简洁而受损

1.png

一般来说,不要缩写名称。尽可能的拼出来,尽管它们可能很长

2.png

您可能认为缩写是中所周知的,但是可能不是这样,特别是遇到您的方法或函数名称的是具有不同的文化和语言背景的开发人员。

然而,一些缩略是真正常见的,具有悠久的使用历史。您可以继续使用它们;请参阅 Acceptable Abbreviations and Acronyms

** 避免API名称中的歧义,例如可以以多种方式解释的方法名称。**

3.png

一致性

** 尝试在整个Cocoa编程接口中使用名称。如果您不确定,请浏览当前头文件或参考文档以获取先例**

当你有一个类的方法需要利用多态时,一致性时特别重要的。在不同类中执行相同的操作方法,应该具有相同的名称

4.png

另请参见Method Arguments

非自我引用

名称不应该时自引用的

5.png

作为掩码(因此可以按位操作组合)的常量是此规则的一个例外,通知名称的常量也是例外。

6.png

前缀

前缀是编程接口中名称的重要组成部分。它们区分软件的功能区域。通常这个软件包装在一个框架中,或者在紧密相关的框架中(如基金会和应用程序包的情况)。前缀可防止第三方开发人员和Apple定义的符号之间的冲突(以及Apple自己的框架中的符号之间)。

前缀具有规定的格式。它由两个或三个大写字母组成,不使用下划线或“子前缀”。以下是一些示例

7

命名类,协议,函数,常量和typedef结构时使用前缀。千万不能命名方法时,使用前缀;方法存在于定义它们的类创建的命名空间中。另外,不要使用前缀来命名结构的字段。

排版约束

命名API元素时,请遵循一些简单的排版约定:

  • 对于由多个单词组成的名称,请勿使用标点符号作为名称或分隔符非一部分(下划线、破折号等);相反,大写每个单词的第一个字母,并把这些单词组合到一起(例如runTheWordsTogether) - 这被称为驼峰命名法。但是,请注意以下资格:
    • 对于方法名称,请从小写字母开始,并将单词的第一个字母大写。不要使用前缀。
fileExistsAtPath:isDirectory:

这个指南的一个例外是以一个著名的首字母缩写开头的方法名称,例如TIFFRepresentation(NSImage)。

  • 对于函数和常量的名称,使用与相关类相同的前缀,并将嵌入字的第一个字母大写。
NSRunAlertPanel
NSCellDisabled
  • 避免使用下划线字符作为方法名称中的私有的前缀(允许使用下划线字符作为实例变量名称的前缀)。苹果保留这个使用这个惯例。第三方的使用可能导致命名空间的冲突;他们可能会无意中用自己的一种方法覆盖现有的私有方法,造成灾难性的后果。有关私有API遵循的约定的建议,请参阅私有方法

类和协议名称

一个类的名字应该明确指出类(或类的对象)代表或做什么的名词。该名称应该有一个适当的前缀。基础和应用框架充满了实例;例如:NSString,NSDate,NSScanner,NSApplication,UIApplication,NSButton,和UIButton。

协议应根据他们的行为组合来命名:

  • 大多数协议组相关的方法,与任何类都没有关联。这种类型的协议应该以不与一个类混淆的方式命名。一种常用的做法是使用动名词形式("...ing")例如:
8
  • 一些协议组合了一些不相关的方法(而不是创建几个单独的小协议)。这些协议通常与作为协议主要表达式的类相关联。在这些情况下,约定是给协议与类相同的名称。

这种协议的一个例子是NSobject协议。此协议的分组的方法可以用于查询其在类层次结构中的位置的任何对象,以使其调用特定方法,并增加或减少其引用计数。因为NSObject类提供了这些方法的主要表达式,所以协议以类命名。

头文件

如何命名头文件很重要,因为您使用的约定表示文件包含了什么:

  • 声明一个孤立的类或协议。如果类或协议不是组的一部分,请将其声明放在单独的文件中,其名称是声明的类或协议的文件。
9
  • 声明相关的类和协议。对于一组相关的声明(类,类和协议),将声明放在一个包含主类,类别或协议的名称的文件中。
10
  • 包含框架头文件。每个框架应该有一个头文件,以框架命名,包括框架的所有公开头文件。
11
  • 将API添加到另一个额框架中的类中。如果您在一个框架中声明在另一个框架的类的类别中的方法,则将“Additions”附加到原始类的名称; 一个例子是 Application Kit 的头文件NSBundleAdditions.h 。
  • 相关功能和数据类型。如果您有一组相关函数,常量,结构和其他类型数据,请将它们放在适当命名的头文件中。(例如:Application Kit 的NSGraphics.h)。
最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 201,924评论 5 474
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 84,781评论 2 378
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 148,813评论 0 335
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,264评论 1 272
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,273评论 5 363
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,383评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 37,800评论 3 393
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,482评论 0 256
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 40,673评论 1 295
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,497评论 2 318
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,545评论 1 329
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,240评论 4 318
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 38,802评论 3 304
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,866评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,101评论 1 258
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 42,673评论 2 348
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,245评论 2 341

推荐阅读更多精彩内容

  • Cocoa代码风格指南之命名规范(一) Cocoa代码风格指南之排版规范(二) Cocoa代码风格指南之注释规范(...
    xuyafei86阅读 3,346评论 0 8
  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 134,573评论 18 139
  • 开发cocoa框架、插件或者其它带公共API的可执行文件需要不同于应用开发一些方法和惯例。你的产品的主要客户是开发...
    酱油不爱醋阅读 1,628评论 0 4
  • 翻译自“Coding Guidelines for Cocoa” 0 简介 使用公开的API开发一个Cocoa框架...
    lakerszhy阅读 1,076评论 0 6
  • Spring Boot 参考指南 介绍 转载自:https://www.gitbook.com/book/qbgb...
    毛宇鹏阅读 46,714评论 6 342