Objective-C 代码规范 (译)

---

Preface

Version: 0.9.0
Our general coding conventions at Spotify are documented on an internal wiki, but specifics for Objective-C and Objective-C++ code in the iOS client are documented here.

Spotify通用的代码规范公约在内部的wiki上，但是特定于Objective-C和Objective-C++的iOS客户端代码规范刊发于此。

License

Copyright (c) 2015-2016 Spotify AB.
This work is licensed under a Creative Commons Attribution 4.0 International License.

---

Table of Contents (目录)

1. Spacing, Lines and Formatting (空格，行和格式化)
2. Brackets (括号)
3. Naming (命名)
4. Comments (注释)）
5. Pragma Marks
6. Constants (常量)
7. Return Early (Return Early原则)
8. Initializers (初始化)
9. Headers
10. Nullability
11. Strings (字符串)
12. Dot Notation (点语法)
13. Categories (类目)

---

Spacing, Lines and Formatting (空格，行和格式化)

Line length (行的长度)

• Keep your lines within 120 characters width when possible.
  • In Xcode, you can set a page guide in Text Editing in Preferences.
• 尽可能保持代码每行不超过120个字段。
  • 在Xcode中，你可以设置在 Preferences -》 Text Editing 中配置page guide。

Whitespace (空格)

• Use 4 spaces for indentation and alignment. Do not use tabs.

• Trailing whitespace is acceptable only on blank lines, but discouraged even there.

  • In Xcode, select "Automatically trim whitespace" and "Including whitespace-only lines" in Text Editing preferences
    to handle this automatically.

• Put spaces after commas, and before and after operators.

• Do not put spaces between parentheses and what they are enclosing.

• 使用 4 个空格作为缩进和对齐，不要用tab。

• 仅在空白行中以空格结尾是可以接受的，尽管如此也不推荐。

  • Xcode中，在 Preferences -》 Text Editing 中勾选 Automatically trim whitespace 和 Including whitespace-only lines可以自动处理行尾空白。

• 逗号后添加空格，运算符前后均添加空格。

• 不要在圆括号及其包括内容之间添加空格。

Example:

foo("bar") 

Not:

foo( "bar" )

Containers (容器)

• Array one-liners are acceptable unless they have too many items or their values are too long.
• 尽可能保持数组单行显示，除非有很多项或者数组的值太长。

NSArray *array = @[@"uno", @"dos", @"tres", @"cuatro"];

• In that case, break them in several lines:
• 在数组无法单行显示的情况下，将数组拆成多行。

NSArray *array = @[
    @"This is how we do, yeah, chilling, laid back",
    @"Straight stuntin’ yeah we do it like that",
    @"This is how we do, do do do do, this is how we do",
];

• Dictionary one-liners are reserved for single pairs only:
• 字典仅在只有一对键值对的情况下单行显示。

NSDictionary *dict = @{@"key" : @"highway"};

• Format it pretty otherwise, leaving a trailing comma after the last item:
• 在其他情况将其格式化对齐，在最后一个键值对后保留逗号。

NSDictionary *dict = @{
    @"key1" : @"highway",
    @"key2" : @"heart",
};

---

Brackets (括号)

• Always use brackets for if / for / while / do-while statements. Even if its a one-liner:
• 在 if / for / while / do-while 语句中，即使只有一行也要使用花括号。

if (itsMagic) {
    [self makeItEverlasting];
}

• Write follow up else clauses after the previous closing bracket on the same line.
• 使用else时，保持其与上一个右括号在同一行。

if (hasClue) {
    knowExactlyWhatToDo();
} else if (seeItAllSoClear) {
    writeItDown();
} else {
    sing();
    dance();
}

---

Naming (命名规则)

• Follow Apple’s Coding Guidelines for Cocoa
  on naming.
• 遵守Apple的 Coding Guidelines for Cocoa 命名规则。

---

Comments (注释)

• Use the // style for single line comments or when appending comments in the same line of code.

• 使用//添加单行注释或在代码行尾添加注释。

• Use the /* */ style for multi-line comments.
• 使用/* */添加多行注释。

Example:

/*
 This is a multi-line comment. The opening and closing markers are on their
 own lines.

 This is a new paragraph in the same block comment.
 */

stop(); // Hammer-time!

// this is a very brief comment.

• Document all methods and properties in the headers using Xcode’s documentation style. You can select a property
  or method and use Cmd-/ to see this in action. Make sure to use the available markup tags like @param,
  @return, etc. (these will be auto-generated for you by Xcode). The /// form is preferred for single line
  comments, and /** */ for multi-line comments. Use the same formatting as in the example block above.

• 使用Xcode官方文档样式记录头文件的所有方法和属性。可以通过选中属性或者使用 Cmd-/ 组合键来查看注释。确保使用@param,@return等可用的标记（这些将由Xcode为您自动生成）。单行注释首选 ///，多行注释使用 /** */。格式与上述的示例相同。

---

Pragma Marks

• Use the pre-processor instruction #pragma mark to mark related groups of methods.
• 使用预处理器指令 #pragma mark 来标记相关的一组方法。

---

Constants (常量)

• Do not define constants using #define.
• 不要使用 #define 定义常量。
• Publicly (or privately) exposed variables should be constant (trying to assign values will result in compilation
  error).
• 公开的（或者私有）暴露的变量应是常量（尝试赋值会导致编译错误）。

extern NSString * const SPTCodeStandardErrorDomain;

---

Return Early (Return Early原则)

• Return early on errors and failed pre-conditions to avoid unnecessary nested brackets and / or unnecessary
  computations.
• 在发生错误时提前返回，借此避免不必要的括号嵌套和/或不必要的计算。

Example:

- (void)setFireToTheRain:(id)rain
{
    if ([_rain isEqualTo:rain]) {
        return;
    }

    _rain = rain;
}

---

Initializers (初始化)

• Follow Apple's typical init format to initialize objects.
• 按照 Apple's typical init format 来初始化对象。

Example:

- (instancetype)init 
{
    self = [super init];
 
    if (self) {
        // initialize instance variables here
    }
 
    return self;
}

---

Headers

• The use of prefix headers has been deprecated. Do not add new code to an existing prefix header.
• prefix headers 已经被弃用了。不要添加新的代至到已有的 prefix header。
• When importing a module use the hash-import variant instead of at-import.
• 当引入模块时，使用 #import 而不是 @import
  • Yes: #import <Foundation/Foundation.h>
  • No: @import Foundation;

---

Nullability

• Use NS_ASSUME_NONNULL_BEGIN and NS_ASSUME_NONNULL_END in header files, and explicitly add nullable when needed. Example:
• 在头文件中使用 NS_ASSUME_NONNULL_BEGIN 和 NS_ASSUME_NONNULL_END，并且在需要时显式添加 nullable。

#import <Foundation/Foundation.h>

@protocol SPTPlaylist;

NS_ASSUME_NONNULL_BEGIN

typedef void(^SPTSomeBlock)(NSData * _Nullable data, NSError * _Nullable error);

@interface SPTYourClass : NSObject

@property (nonatomic, copy, readonly, nullable) NSString *customTitle;
@property (nonatomic, strong, readonly) id<SPTPlaylist> playlist;

- (nullable instancetype)initWithPlaylist:(id<SPTPlaylist>)playlist
                              customTitle:(nullable NSString *)customTitle;

@end

NS_ASSUME_NONNULL_END

---

Strings (字符串)

• All strings presented to the user should be localized.
• 所有呈现给用户的字符串都应该被本地化。

---

Dot Notation (点语法)

• Use bracket notation when calling non-accessor methods:
• 使用非访问器方法时，使用括号表示法。

[self doSomething];

• Use bracket notation when accessing globals through a class method:
• 通过类方法访问全局变量时，使用括号表示法。

[MyClass sharedInstance];

• Set and access properties using dot notation:
• 赋值和取值时使用点表示法。

self.myString = @"A string";

• Except in the init or dealloc methods, always use the ivar directly there:
• 除了 init 和 dealloc 方法之外，其他地方全部直接使用实例变量的形式。

_myString = nil;

---

Categories (类目)

• Methods in categories on non-Spotify classes must be prefixed spt_ to avoid name clashes.
• 非Spotify类中的类目方法必须以spt_为前缀，以避免名称冲突。