加载中

Important Note

Displaying Hidden Details in this Guide

This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. You should see "Hooray" appear below.

Background

Objective-C is a very dynamic, object-oriented extension of C. It's designed to be easy to use and read, while enabling sophisticated object-oriented design. It is the primary development language for new applications on Mac OS X and the iPhone.

Cocoa is one of the main application frameworks on Mac OS X. It is a collection of Objective-C classes that provide for rapid development of full-featured Mac OS X applications.

注意事项

显示在本指南中隐藏细节

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

背景

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

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

Apple has already written a very good, and widely accepted, coding guide for Objective-C. Google has also written a similar guide for C++. This Objective-C guide aims to be a very natural combination of Apple's and Google's general recommendations. So, before reading this guide, please make sure you've read:

Note that all things that are banned in Google's C++ guide are also banned in Objective-C++, unless explicitly noted in this document.

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

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

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

The purpose of this document is to describe the Objective-C (and Objective-C++) coding guidelines and practices that should be used for all Mac OS X code. Many of these guidelines have evolved and been proven over time on other projects and teams. Open-source projects developed by Google conform to the requirements in this guide.

Google has already released open-source code that conforms to these guidelines as part of the Google Toolbox for Mac project (abbreviated GTM throughout this document). Code meant to be shared across different projects is a good candidate to be included in this repository.

Note that this guide is not an Objective-C tutorial. We assume that the reader is familiar with the language. If you are new to Objective-C or need a refresher, please read The Objective-C Programming Language .

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

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

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

Example

They say an example is worth a thousand words so let's start off with an example that should give you a feel for the style, spacing, naming, etc.

An example header file, demonstrating the correct commenting and spacing for an@interfacedeclaration

#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

An example source file, demonstrating the correct commenting and spacing for the@implementationof an interface. It also includes the reference implementations for important methods like getters and setters,init, anddealloc.

#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

Blank lines before and after@interface,@implementation, and@endare optional. If your@interfacedeclares instance variables, a blank line should come after the closing brace (}).

Unless an interface or implementation is very short, such as when declaring a handful of private methods or a bridge class, adding blank lines usually helps readability.

例子

他们说一个例子胜过千言万语,让我们开始用一个例子让你感受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
一个源文件的例子,展示了一个接口的@implementation的正确注释和间距。它也包含一些重要方法,像getters、setters、init和dealloc的参考实现:
#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和@end前后的空行是可选的。如果你的@interface声明了实参,那么右括号之后需要有一个空行。

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

Spacing And Formatting

Spaces vs. Tabs

Use only spaces, and indent 2 spaces at a time.

Line Length

Each line of text in your code should try to be at most 80 characters long.

Method Declarations and Definitions

One space should be used between the-or+and the return type, and no spacing in the parameter list except between parameters.

Method Invocations

Method invocations should be formatted much like method declarations. When there's a choice of formatting styles, follow the convention already used in a given source file.

@public and @private

The@publicand@privateaccess modifiers should be indented by 1 space.

间距和格式

空格(spacing)与制表符(tab)

仅使用空格,每次缩进2个空格。

每行的宽度

应尽量在你的代码中将每行控制在80个字符内。

方法的声明和定义

在-(或+)与返回值类型中间须要有一个空格,在参数列表中,除了参数之间不要有任何间距。

方法调用

方法调用的格式须要与定义时个格式一致。当有多种格式化的样式可供选择的时候,按照惯例,采用在给定的源文件中使用过的那个方式。

@public与@private

@public与@private访问修饰符后边须要有一个空格。

Exceptions

Format exceptions with each@label on its own line and a space between the@label and the opening brace ({), as well as between the@catchand the caught object declaration.

Protocols

There should not be a space between the type identifier and the name of the protocol encased in angle brackets.

Blocks

Blocks are preferred to the target-selector pattern when creating callbacks, as it makes code easier to read. Code inside blocks should be indented four spaces.

Exceptions

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

Protocols

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

Blocks

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

Naming

Naming rules are very important in maintainable code. Objective-C method names tend to be very long, but this has the benefit that a block of code can almost read like prose, thus rendering many comments unnecessary.

When writing pure Objective-C code, we mostly follow standard Objective-C naming rules. These naming guidelines may differ significantly from those outlined in the C++ style guide. For example, Google's C++ style guide recommends the use of underscores between words in variable names, whereas this guide recommends the use of intercaps, which is standard in the Objective-C community.

Any class, category, method, or variable name may use all capitals for initialisms within the name. This follows Apple's standard of using all capitals within a name for initialisms such as URL, TIFF, and EXIF.

命名

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

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

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

When writing Objective-C++, however, things are not so cut and dry. Many projects need to implement cross-platform C++ APIs with some Objective-C or Cocoa, or bridge between a C++ back-end and a native Cocoa front-end. This leads to situations where the two guides are directly at odds.

Our solution is that the style follows that of the method/function being implemented. If you're in an@implementationblock, use the Objective-C naming rules. If you're implementing a method for a C++class, use the C++ naming rules. This avoids the situation where instance variable and local variable naming rules are mixed within a single function, which would be a serious detriment to readability.

然而,在编写Objective-C++代码时,往往并非能完全按照规范来进行。很多项目会使用Objective-C,或是Cocoa,或是C++后端与原生的Cocoa前端通信的方式来实现跨平台的C++ API。这就导致了两种语言规范直接冲突的情况。

我们的解决方法是依据方法/函数具体实现的方式来决定命名。如果你在一个@implementationblock里面,就使用Objective-C的命名规范。如果你在一个C++类里面实现一个方法,就使用C++命名规范。这就避免了在一个函数中实例变量和本地变量的命名规则混合使用的情况,减少了对代码的可阅读性造成的极大损害。

File Names

File names should reflect the name of the class implementation that they contain—including case. Follow the convention that your project uses.

Objective-C++

Within a source file, Objective-C++ follows the style of the function/method you're implementing.

Class Names

Class names (along with category and protocol names) should start as uppercase and use mixed case to delimit words.

Category Names

Category names should start with a 2 or 3 character prefix identifying the category as part of a project or open for general use. The category name should incorporate the name of the class it's extending.

Objective-C Method Names

Method names should start as lowercase and then use mixed case. Each named parameter should also start as lowercase.

Variable Names

Variables names start with a lowercase and use mixed case to delimit words. Instance variables have leading underscores. For example:myLocalVariable,_myInstanceVariable.

文件名

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

Objective-C++

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

类名

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

分类名称

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

Objective-C 方法名称

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

变量名

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

Comments

Though a pain to write, they are absolutely vital to keeping our code readable. The following rules describe what you should comment and where. But remember: while comments are very important, the best code is self-documenting. Giving sensible names to types and variables is much better than using obscure names and then trying to explain them through comments.

When writing your comments, write for your audience: the next contributor who will need to understand your code. Be generous—the next one may be you!

Remember that all of the rules and conventions listed in the C++ Style Guide are in effect here, with a few additional points, below.

注释

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

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

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

返回顶部
顶部