googleOjbectc规范_计算机软件及应用_IT计算机_专业资料.docx

Gooqle 的 Obiective-C 编码规范文章分类:移动开发原文 Gooale Obiective-C Stvle GuideiPhone项冃新成立,也没有编码规范的积累,项冃组本米是想拿老的C编码规范套用的,但评审 就发现问题多多，之后找到了 Google的Objective-C的编码规范，大家就先翻译一下咯声明这是无版权翻译,也不对任何错误负责，不保证文章的完整性,我到现在也认不全语法。总览背景知识Objective-C是个C语言的扩展语言,非常动态,非常的“面向对象”,它被设计成既拥有复杂的面 向对象设计理念又可以轻松使用与阅读的语言,也是MacS X和iPhone开发的首选语言。Cocoa是Mac OS X的主要应用框架,提供迅速开发各种功能的Mac OS X应用的Objective-C类集 合。Apple已经有一个很好也被广泛接受的Objective-C的编码规范,Google也有类似的C+编码规范, 这份。bjective-C编码规范很自然是Apple和Google的共同推荐的组合。所以,在阅读本规范前,确保你 已经阅读了:Apple's Cocoa Codina GuidelinesGoogle's Open Source C+ St+le Guide注意所有已在Google的C+编码规范里的禁用条款在。bjective-C里也适用,除作本文档明确指出 反对意见。本文档旨在描述可供可适用于所有Mac OS X代码的Objective-C（包括Objective-C+）编码规范和实 践。规范中的许多条款已经改进也不断的被其他的项目和团队所证明其指导性。Google的相关开源项目都 遵守此规范。Google已经发布了 份作为Gooqle Toolbox for Mac project （文档中简称为GTM）的组成部分的遵 守本规范的开源代码。这份开放代码也是本文很好的例证（原文看不太懂Code meant to be shared across different projects is a good candidate to be included in this repository.）注意本文不是bjective-C的教学指南,我们假设读者已经了解语言。如果你是个。bjective-C的 初学者或需要重温,请阅读The。60近CProgramming Language .人们说个例子胜过千言万语,所以就让我们用例子来让你感受以下编码规范的风格,留间距,命名下例是份头文件,展示对访1。什20声明正确的注释和留间距Java代码1. /GTMFoo.h2. /FooProject3. /4. /Created byGreg Milleron6/13/08.5. /Copyright 2008 Google,Inc.Allrights reserved.6. /7.8. #import <Foundation/Foundation.h>9.10. / A sample class demonstrating good Objective-C style. All interfaces,11. / categories, and protocols (read: all top-level declarations in a heade r)12. / MUST be commented. Comments must also be adjacent to the object they * re13. / documenting.14. /15. / (no blank line between this comment and the interface)16. ©interface GTMFoo : NSObject 17. ©private18. NSString *foo_；19. NSString *bar_;20. 21.22. / Returns an autoreleased instance of GMFoo. See -initWithString: for detai Is23. / about the argument.24. + (id)fooWithString:(NSString *)string;25.26. / Designated initializer. |string| will be copied and assigned to |foo_|.27. - (id)initWithString:(NSString *)string;28.29. / Gets and sets the string for |foo.30. - (NSString *)foo;31. - (void)setFoo:(NSString *)newFoo;32.33. / Does some work on |blah| and returns YES if the work was completed34. / successfuly, and NO otherwise.35. - (BOOL)doWorkWithString:(NSString *)blah;36.37. end下例是一份源文件,展示对接口的implementation的实现的正确注释和留间隔。它也包括了主要方 法如 getters,setters,init,和 dealloc 的相关实现。Java代码1. /2. /GTMFoo.m3. /FooProject4. /5. /Created byGreg Milleron6/13/08.6. /Copyright 2008 Google,Inc.Allrights reserved.7. /8.9. #import "GTMFoo.h"10.11.12. 0implementation GTMFoo13.14. + (id)fooWithString:(NSString *)string 15. return self alloc initWithString:string autorelease;16. 17.18. / Must always override super's designated initializer.19. - (id)init 20. return self initWithString:nil;21. 22.23. - (id)initWithString:(NSString *)string 24. if (self = super init) 25. foo_ = string copy;26. bar_ = NSString alloc initWithFormat:"hi %d", 3;27. 28. return self;29. 30.31. - (void)dealloc 32. foo_ release;33. bar_ release;34. super dealloc;35. 36.37. - (NSString *)foo 38. return foo_;39. 40.41. - (void)setFoo:(NSString *)newFoo 42. foo_ autorelease;43. foo_ = newFoo copy;44. 45.46. - (BOOL)doWorkWithString:(NSString *)blah 4748. return NO;49. 50.51. end间隔与格式化空格对tab键仅使用空格,缩进两个。我们使用空格用于缩进,不要在编码时使用tab键,你应该设置你的编辑器将tab键转换成对应的空 格。行长度代码中的每行文本不要超过80个字符的长度。尽管。bjective-C正变得比C+更加繁冗,为了保持规范的互通性,我们还是决定保持80字符长度 的限制。这比你想象中的更容易做到。我们知道本条款是有争议的，但已有此多的代码己经遵从了本条款,即使只是保持致性也是个充 足的理由。你可以在Xcode里清楚地发现代码中的违规，设置Xcode > Preferences > Text Editing > Show page guide.（之后就可以在代码编辑区域里看到条指定字符长度的指示线了）方法声明与定义留一个空格在或+和返冋类型之间,但参数列表里的参数之间不要留间隔。方法应该写成这样:Java代码1. - (void)doSomethingWithString:(NSString *)theString 3星号前的空格是可选的,你可以根据原来的代码风格门行决定。如果参数过多,推荐每个参数各占一行。使用多行的情况下,以参数前的冒号用于对齐:(很遗憾这里仅有Google Chrome浏览器能看出是冒号对齐的)Java代码2. - (void)doSomethingWith:(GTMFoo *)theFoo3. rect:(NSRect)theRect4. interval:(float)thelnterval 5. .6. 当第一个关键字比其他的短时,后续行至少缩进四个空格。这样你可以让后续的关键字垂直对齐,而 不是用冒号对齐:Java代码1. - (void)short:(GTMFoo *)theFoo2. longKeyword:(NSRect)theRect3. evenLongerKeyword:(float)thelnterval 4. .5. 方法调用方法调用的格式和方法声明时的格式时一致的,如果格式风格可选,遵从原有代码的风格。调用应该将所有参数写在一行:Java代码1. myObject doFooWith:argl name:arg2 error:arg3;或者每个参数一行,用冒号对齐:（对齐效果如前说明）Java代码2. myObject doFooWith:argl3. name:arg24. error:arg3;不要使用如下风格的写法Java代码123456789myObject doFooWith:argl name:arg2 / some lines with >1 arg error:arg3;myObject doFooWith:arglname:arg2 error:arg3;myObject doFooWith:arglname:arg2 / aligning keywords instead of colons error:arg3;在声明和定义时,如果因为关键字长度使就算有四个空格在前仍然无法用冒号对齐,那么就让后续行 缩进四个空格而不是冒号对齐:Java代码1. myObj short:argl2. longKeyword:arg23. evenLongerKeyword:arg3;public 和 private权限控制符public和private缩进个空格.类似 C+的 public,protected,private:Java代码1. ginterface MyClass : NSObject 2. public3. 4. 0private5. 6. 7. end异常每个异常标签的和开括号(写在统行,标签和开括号间隔个空格,同样适用于catch语句。如果你决定使用bjective-C的异常,那么就按如下格式,不过你最好先看看Avoid Throwing Exceptions(见后)条款,了解为何你不应使用异常。Java代码1. try 2. foo();3. 4. catch (NSException *ex) 5. bar(ex);6. 7. 0finally 8. baz();9. 命名命名规则对于维护代码来说是非常重要的。Objective-C方法名往往很长,不过这也有好处，读代码 就像读散文(放屁),让很多注释变得毫无意义。写纯Objective-C代码时，我们基本上遵守标准Obiective-C namina rules ,这些规则和C+的规则 有很大的不同。比如Google的C+代码规范推荐变量名构词之间使用下划线隔开,而本文档推荐驼峰法, 也是bjective-C社区的标准。所有类，类别,方法,以及变量如包括缩写,则缩写部分使用全大的缩写(Initialisms)形式。这遵守 Apple的标准，比如URL,TIFF以及EXIF。当写Objective-C+代码时,情况就不是那么单一了。许多项冃需要实现带些Objective-C代码的跨 平台的C+APIS或者连接后台的C+代码与前台的原生Cocoa代码.这会造成两种规范直接冲突。我们的解决方法是根据方法/函数风格来决定。如果在Qimplementation块,就使用Objective-C的命 名规则:如果在C+的方法实现块,就使用C+的命名规则。避免了实体变量和本地变量在一个函数内命 名规则冲突的情况,而这种情况是对可读性的极大损害。文件命名文件名反映了它所包含的实现类的名字,遵从你所在项冃的习惯。文件扩展名使用如下规则.h C/C+/Objective-C header file .m Objective-C implementation file .mm Objective-C+ implementation file .cc Pure C+ implementation file.cC implementation file类别的文件名应该包含扩展类的名字,比如GTMNSString+Utils.h or GTMNSTextView+Autocomplete.hObjective-C+在份源文件里,Objective-C+代码遵守当前方法/函数的风格为了尽量减少不同命名风格间的冲突，使用当前方法的风格。如果在implementation块，使用 Objective-C命名规则,如果在C+类的函数实现块,使用C+命名规则。Java代码1. / file: cross_platform_header.h2.3. class CrossPlatformAPI 4. public:5. .6. int DoSomethingPlatformSpecific(); / impl on each platform7. private:8. int an_instance_var_;9；10.11. / file: mac_implementation.mm12. #include Mcross_platform_header.h"13.14. / A typical Objective-C class, using Objective-C naming.15. interface MyDelegate : NSObject 16. gprivate17. int instanceVar_;18. CrossPlatformAPI* backEndObject_;19. 20. - (void)respondToSomething:(id)something;21. end22. 0implementation MyDelegate23. - (void)respondToSomething:(id)something 24. / bridge from Cocoa through our C+ backend25. instanceVar_ = backEndObject->DoSomethingPlatformSpecific();26. NSString* tempString = NSString stringWithlnt:instanceVar_;27. NSLog("%", tempString);28. 29. end30.31. / The platform-specific implementation of the C+ class, using32. / C+ naming.33. int CrossPlatformAPI:DoSomethingPlatformSpecific() 34. NSString* temp_string = NSString stringWithlnt:an_instance_var_;35. NSLog("%", temp_string);36. return temp_string intValue;37. )类命名类名（不包括类别和协议名）应该用大写开头的驼峰命名法。在应用级别的代码里,尽量不要使用带前缀的类名。每个类都有相同的前缀不能提高可读性。不过如 果是编写多个应用间的共享代码,前缀就是可接受并推荐的做法了（型如GTMSendMessage ）.类别命名类别命名应该以两三个字符的分类前缀作为一个项目或通用的公用部分。类别名应该包含类的扩展。举个例子,如果我们想要创建一个基于NSString的类别用于解析,我们应该把类别放到名字是 GTMNSString+Parsing.h的文件里,而类别本身的名字则是GTMStringParsingAdditions (是的,我们明白 这个类别和其文件名字不匹配,但这个文件可能还包括其他用于解析相关的类别)。类别的方法应该都使用 个前缀(型如gtm_myCategoryMethodOnAString ),以防止bjective-C代码在单名空间里冲突。如果代 码本来就不考虑共享或在不同的地址空间(addressspace),方法命名规则就没必要恪守了。Objective-C方法命名方法使用小写开头的驼峰法命名,每个参数都应该小写开头。方法名应该尽可能读起来像一句话,参数名就相对方法名的补充说明(比如convertPoing寸romRect:或 者 replaceCharacterslnRange:withString:),详见 Apple's Guide to Naming Methods存取(Accessor)方法应该一致的在"取(geHing)”的时候直接用变量名而不是在签名加,get”,如: Java代码1. - (id)getDelegate; / AVOID2.3. - (id)delegate; / GOOD不过这仅针对bjective-C代码,C+代码仍然遵循自己的代码规范。变量命名变量名使用小写开头的驼峰法,类成员变鼠名最后加一个下划线,比如:myLovalVariable, mylnstanceVariable_,下面看不懂,原文 Members used for KVO/KVC bindings may begin with a leading underscore iff use of Objective-C 2.0's ©property isn't allowed.一般变量命名不要使用匈牙利命名法去标记语法,比如静态类型或变量类型(int或pointer之类的)。使变量名尽量 可以推测其用途属性具有描述性。别心想着少打儿个字母,让你的代码可以迅速被理解更加重要。比如: Java代码1. / AVOID2. int w;3. int nerr;4. int nCompConns;5. tix = NSMutableArray alloc init;6. obj = someObject object;7. p = network port;8.9. GOOD10. int numErrors;11. int numCompletedConnections;12. tickets = NSMutableArray alloc init;13. userinfo = someObject object;14. port = network port;实体变量实体变量用驼峰法命名并后缀下划线,就像usemameTextField_.然而我们允许种例外就是用 KVO/KVC去绑定一个实体变量而Objective-C 2.0不能用(因为操作系统的限制)的情况,此时也可用前缀 下划线的方法给毎个变量命名。如果可以使用bjective-C 2.0, ©property和synthesize提供了遵守命 名规范的解决方法。常量常量(预定义,枚举,局部常量等)使用小写k开头的驼峰法,比如klnvalidHandle , kWritePerm .注释尽管写起来很痛苦,但注释仍然是使代码保持可读性的极端重要的方式。下面的条款描述了你应该注 释什么以及在哪里做注释。但是记住:即使注释是如此重要,最好的代码还是自说明式的。起个有意义的 名字比起一个晦涩的名字然后在用注释去解释它好的多。当你写注释的时候，记住注释是写给读者,即下个要理解你的代码并继续开发的人。“下一个“完全 可能就是你自己。同样,所有C+编码规范的条款仍然适用,只是增加了一些条款,如下.文件注释每个文件的开头都是版权声明,接着是文件内容的描述。法律声明和作者栏每个文件都应该包含如下信.息:一份版权声明(比如 Copyright 2008 Google Inc .)许可版本为项目选择合适的许可版本(比如Apache 2.0, BSD, LGPL, GPL)如果你把别人写的文件做了相当大的改动,就把自己添加到作者栏去。这样别的开发者就方便联系这 个文件的实际开发人员了。声明注释每个接口,类别,协议都必须伴随描述它的用途以及如何整合的注释。Java代码1. / A delegate for NSApplication to handle notifications about app2. / launch and shutdown. Owned by the main app controller.3. ©interface MyAppDelegate : NSObject 1 5 .6 . end如果已经在文件的顶部写了接口的详细描述,你也可以简单的写如”见文件顶部的完整描述”,当然要 有这些注释的顺序安排。此外public接口的每个方法都应该添加关于函数,参数,返回值以及副作用的注释。文档默认类都是同步的,如果类实例可以多线程访问,必须要加上额外的说明。实现注释使用竖线引用变量或符号,而不是用引号。这可以减少歧义,特别是当符号本身就是个常见的词时,可能使句子显得支离破碎,比如符号是"count":Java代码1. / Sometimes we need |count| to be less than zero.或者是对于那些已经存在引号的情况Java代码2. / Remember to call |StringWithoutSpaces("foo bar baz")|对象所有权使指针所有权的模型尽可能清晰,当它属丁bjective-C的使用惯例时(不懂,原文是Make the pointer ownership model as explicit as possible when it falls outside the most common Objective-C usage idioms.)实例变量指向NSbject派生类的对象时都假定是retain的,如果它们不是retain的则需要加上“weak” 的文档说明。对应的,实体变量如果标记上旧utlets则是假定为非retain的,若实际上用了 retain,就必 须加上"strong”的说明。当实例变量指向核心库,C+或其他非bjective-C对象时,必须永远用注释说明是strong还是weak 的。必须注意为了支持bjective-C对象里的自动化C+対象的封装是默认被关闭的的(这句话有歧义,原 文是 Be mindful that support for automatic C+ objects encapsulated in Objective-C objects is disabled by default),这屮.有说明。strong和weak说明的文档示例:Java代码3. interface MyDelegate : NSObject 4. private5. IBOutlet NSButton* okButton / normal NSControl6. IBOutlet NSMenu* myContextMenu_; / manually-loaded menu (strong)7.8. AnObjcObject* doohickey / my doohickey9. MyController* controller_; / so we can send msgs back (weak, owns me)10.11. / non-NSObject pointers.12. CWackyCPPClass* wacky / some cross-platform object (strong)13. CFDictionaryRef* diet (strong)14. 15. endstrong对象会在类中retainweak对象不会在类中retain (比如一个委托)Cocoa 和 Objective-C 特性成员变量应该定义为privateJava代码1. ginterface MyClass : NSObject 2. ©private3. id myInstanceVariable_;4. )5. / public accessors, setter takes ownership6. - (id)mylnstanceVariable;7. - (void)setMylnstanceVariable:(id)theVar;8. end明确指定初始化注释并说明指定的初始化。明确指定初始化对想要子类化你的类的时候时很重要的。那样,子类化时只需要做个或多个初始化 去保证初值即可.这也有助于在以后调试你的类时明了初始化流程。重写指定初始化当重写个子类并需要init方法,注意要重写父类的指定初始化方法。如果你没有正确重写父类的指定初始化方法,你的初始化方法可能不会被调用,这会导致很多微妙而 难以排除的错误。初始化没必要在初始化方法里把变量初始化为或者nil,这是多余的。所有新分配内存的对象内容都初始化为0（除了 isa）,所以不要在init方法里做无谓的重初始化为 的操作。保持公有API简明保持你的类简单，避免"厨房水槽"似的APIs,如果个方法没必要公开就不要公开。使用私有类别保 证公开头文件的简洁。和C+不同,Objective-C无法区分公有私有方法，因为它全是公有的。因此，除非就是为了让用户 调用所设计,不要把其他的方法放到公有API里。这样可以减少不期调用的可能性。这还包括重写父类的 方法。对于那些内部实现的方法,在实现文件里使用类别而不是将方法定义在公有头文件里。Java代码/ GTMFoo.m2. #import "GTMFoo.h"3.4. ginterface GTMFoo (PrivateDelegateHandling)5. - (NSString *)doSomethingWithDelegate; / Declare private method6. end7.8. 0implementation GTMFoo(PrivateDelegateHandling)1.1. .10. - (NSString *)doSomethingWithDelegate 11. / Implement this method12. 13. .14. end在Objective-C 2.0之前,如果你在私有interface里声明了一个方法,但忘记在主 ©implementation文件里实现了,编译器不会有什么反应(这是因为你没有在不同的类别里实现这些私有方 法)。解决方案在是把函数写到implementation里并指明类别。如果你用的是Objective-C 2.0,你应该使用地型而不是声明私有类别,如下:Java代码1. ginterface GMFoo ().如此就可以保证函数做了声明但没有在implememtation里实现的时候编译器会警报。再者,” private”方法并不是真正的private,你可能会无意间重写了父类的个" private”方法,这回导 致bug的涌现。总的来说,私有方法应该使用更特别的名字以阻止子类化时并不期望的重写。最后,对丁绝大多数类而言,bjective-C的类别是将implelemtation做可理解的分块,添加新的应 用级别的功能的最佳途径。比如,与其在你的项目里随便找个类来实现字符串的“中间截断”功能,不如创 建一个新的NSString类别。#import 和 #include用#import导入Objective-C或bjective-C+头文件,用#include导入C或C+头文件根据头文件的语言去选择合适的导入方式。当导入的头文件使用Objective-C或bjective-C+语言时,使用#import.当导入标准C或C+头文件时,使用#include .头文件应该使用自己的#define重加载保护有些bjective-C头文件没有#define重加载保护，所以只应该用#import导入。因此Objective-C头 文件只应该被bjective-C源文件或其他的bjective-C头文件所导入。这种情况下全部使用#impor!是合 适的。标准C和C+头文件不包含任何bjective-C元素都可以被一般的C或C+文件导入。因为标准C 和C+里根本没有#import,所以也只能用#include导入。在Objective-C代码中使用#include 一致的导入 这些头文件。本条款有助于跨平台项冃的无意错误。一位Mac开发者引入份新C或C+头文件时可能会忘记添 加#define重加载保护,因为在Mac上用#import导入文件不会引发问题,但在别的使用#include的平台就 可能出问题。在所有平台一致的使用#include意味着要么全部成功要么全部失败,避免了那种另人沮丧的 些平台上可以运作而另些不行的情况。Java代码1. #import <Cocoa/Cocoa.h>2. #include <CoreFoundation/CoreFoundation.h>3. #import "GTMFoo.h"4. #include "base/basictypes.h"使用框架根导入框架根的头文件而不是分别导入框架头文件看起来从Cocoa或Foundation这些框架里导入个别的文件很不错,但实际上你直接导入框架根头文 件效率更高.框架根已经被预编译故可更快的被加载。还有,记住用#import指令而不是#include导入 Objective-C 的框架。Java代码1. #import <Foundation/Foundation.h> / good2.3. #import <Foundation/NSArray.h>/ avoid4. #import <Foundation/NSString.h>5.构建时即设定autorelease当创建新的临时对象时,在同一行代码里就设定autorelease而不是写到这个方法的后面几行去即使这样可能会造成一些轻微的延迟,但这样避免了谁不小心把release去掉,或在release之前就 return而造成的内存泄露,如下Java代码1. / AVOID (unless you have a compelling performance reason)2. MyController* controller = MyController alloc init;3. / . code here that might return .4. controller release;5.6. / BETTER7. MyController* controller = MyController alloc init autorelease;优先 autorelease 而非 retain对象赋值时尽量采用autorelease而不是retian模式。当把个新创建的对象赋予个变量的时候,第件要做的事情就是先释放原来变量指向的对象以防 止内存泄露。这里也有很多“正确的”方法去做这件事。我们选择autorelease时因为它更不倾向于出错。小 心在密集的循环里可能会很快填满autorelease池,而且它也确实会降低效率,但权衡下来还是可以接受 的。Java代码1. - (void)setFoo:(GMFoo *)aFoo 2. foo_ autorelease; / Won't dealloc if |foo_| = |aFoo|3. foo_ = aFoo retain;4以声明时的顺序dealloc处理实例变量dealloc应该用在interface声明时同样的顺序处理实例变量,这也有助于评审者鉴别。代码评审者检査或修正dealloc的实现要确保所有retain的实例变量都