Google 的 Objective-C 代码规范指南 已翻译 100%

注意事项

显示在本指南中的隐藏细节

这个风格指南包含很多最初不可见的细节。它们被标记为三角形图标，你可以在左边看到。现在点击它，你应该会看到“万岁”出现在下面。

背景

Objective-C是一种很动态的、面向对象的C语言扩展。它被设计成易用易读，同时支持复杂的面向对象设计。它是Mac OS X和iPhone上开发新应用的主要开发语言

Cocoa是在Mac OS X平台上的一个主要的应用框架。这是一个提供给全功能Mac OS X应用程序的快速开发的Objective-C类集合。

Apple已经为Objective-C编写了一本很好的、被广泛接受的编码指南；Google也为C++写了一本类似的指南。这本Objective-C指南意在成为一个对Apple和Google的一般建议的自然组合。因此，在读这本指南之前，确定你已经度过：

• Apple的Cocoa编码指南
• Google的开源C++设计指南

注意：所有在Google C++指南中禁用的在Objective-C++里也一样，除非本文特别指出。

这个文档是为了描述用于所有Mac OS X代码中的Objective-C（和Objective-C++）编码指南和实践的。这些指南的很多地方已经进化并在其他项目和团队已经过时。谷歌开发的开源项目符合本指南中的要求。

谷歌已经发布了符合这些准则的，作为Mac项目的谷歌工具箱（以下简称GTM）的一部分的开源代码。意味着要在不同项目共享的代码是一个包含在这个库中很好的候选。

注意：这本指南不是一个Objective-C教程。我们假设读者对这么语言很熟悉。如果你是一个Objective-C初学者或需要复习，请阅读的Objective-C编程语言这本书。

例子

他们说一个例子胜过千言万语，让我们开始用一个例子让你感受Objective-C的风格，间距，命名等。

一个头文件的例子，展示了@interface声明的正确注释和间距：

#import <Foundation/Foundation.h>

// A sample class demonstrating good Objective-C style. All interfaces,
// categories, and protocols (read: all top-level declarations in a header)
// MUST be commented. Comments must also be adjacent to the object they're
// documenting.
//
// (no blank line between this comment and the interface)
@interface Foo : NSObject {
 @private
  NSString *_bar;
  NSString *_bam;
}

// Returns an autoreleased instance of Foo. See -initWithBar: for details
// about |bar|.
+ (id)fooWithBar:(NSString *)bar;

// Designated initializer. |bar| is a thing that represents a thing that
// does a thing.
- (id)initWithBar:(NSString *)bar;

// Gets and sets |_bar|.
- (NSString *)bar;
- (void)setBar:(NSString *)bar;

// Does some work with |blah| and returns YES if the work was completed
// successfully, and NO otherwise.
- (BOOL)doWorkWithBlah:(NSString *)blah;

@end

#import "Foo.h"


@implementation Foo

+ (id)fooWithBar:(NSString *)bar {
  return [[[self alloc] initWithBar:bar] autorelease];
}

// Must always override super's designated initializer.
- (id)init {
  return [self initWithBar:nil];
}

- (id)initWithBar:(NSString *)bar {
  if ((self = [super init])) {
    _bar = [bar copy];
    _bam = [[NSString alloc] initWithFormat:@"hi %d", 3];
  }
  return self;
}

- (void)dealloc {
  [_bar release];
  [_bam release];
  [super dealloc];
}

- (NSString *)bar {
  return _bar;
}

- (void)setBar:(NSString *)bar {
  [_bar autorelease];
  _bar = [bar copy];
}

- (BOOL)doWorkWithBlah:(NSString *)blah {
  // ...
  return NO;
}

@end

除非interface或implementation很短，比如，当定义一小部分私有方法或一个桥接类时，添加空行通常有利于可读性。

Exceptions

在单独一行时，使用 @ 标签格式化 exceptions，@ 标签和开放括号 ({) 间加一个空格，在@catch 和 对象捕获声明之间也是。

Protocols

在类型标识符和封装在尖括号中的 Protocols 名称之间不应该有空格。

Blocks

Blocks 在创建回调函数时更倾向于目标选择器模式，这可以让代码更易读。块内的代码应缩进4个空格。

命名

命名规则对于代码的可维护性是非常重要的。Objective-C的方法命名趋向于超长命名，但这会带来良好的代码阅读感受，就像读散文一样，同时还避免了很多不必要的注释。

在撰写纯粹的Objective-C代码时，我们主要是遵循标准的Objective-C命名规范。这些命名方针可能和C++的命名规范相去甚远。比如，Google的C++规范中推荐在变量名中的单词间使用下划线，而Objective-C的规范推荐使用驼峰命名法，这也是在Objective-C社区中的标准做法。

任何类、目录、方法或者变量的名字都应该将其中的首字母缩略词设为大写。下面是苹果官方使用的大写的首字母缩略词：URL，TIFF和EXIF。

文件名

文件名应该反映其中包含的类实现的名称，按照你项目中的约定且大小写相关。

Objective-C++

在一个源码文件中， Objective-C++ 遵循你实现的函数/方法的风格。

类名

类名（类别和协议名称）应为大写，并开始使用大小写混合以区分单词。

分类名称

分类名称应该以一个2到3个字母的前缀开始，识别分类是项目的一部分，还是打开使用。分类，名称应该结合它扩展的类的名称。

Objective-C 方法名称

方法名称应该以小写字母开头，混合大小写。每个命名参数也应该以小写字母开头。

变量名

变量名以小写字母开头，混合大小写以区分单词。实例变量以下划线开头。例如：myLocalVariable，_myInstanceVariable。

注释

尽管写的时候很痛苦，但是他们对于保持你代码的可读性来说绝对是至关重要的。下面几条规则描述了你应该什么时候在什么地方加注释。但是要记住，虽然注释很重要，但是最好的代码都是自注释的。给变量和类型一个有意义的名字，要比用一个难懂的名字然后再费力的用注释来解释好得多。

写注释的时候，要写给你的读者：下一个要读懂你代码的贡献者。多写点吧——下个没准就是你自己！

记住所有c++编程规范里列出的规则和协定在这里也是生效的，下面是几点补充。