【objc-zen-book】5.美化代码 & 代码组织

这个小系列是从 "Zen and the Art of the Objective-C Craftsmanship"中进行的摘抄，共分成6篇，大部分是讲代码风格及美化，偶尔看看也不错。

原文GitHub地址:
https://github.com/objc-zen/objc-zen-book
中文版GitHub地址:
https://github.com/oa414/objc-zen-book-cn

美化代码

缩进使用 4 个空格，永远不要使用 tab。（因为不同的文字处理程序对tab可能有不同的处理，在你这里是4个空格，在别的地方可能就不是了。）

if/else/switch/while 的大括号总是在同一行开始，在新起一行结束。

// 推荐
if (user.isHappy) {
    //Do something
}
else {
    //Do something else
}

// 不推荐
if (user.isHappy)
{
  //Do something
} else {
  //Do something else
}

方法之间应该要有一个空行来帮助代码看起来清晰且有组织。方法内的空格应该用来分离功能，但是通常不同的功能应该用新的方法来定义。

应该总是让冒号对齐。有一些方法签名可能超过三个冒号，用冒号对齐可以让代码更具有可读性。即使有代码块存在，也应该用冒号对齐方法。

// 推荐
[UIView animateWithDuration:1.0
                 animations:^{
                     // something
                 }
                 completion:^(BOOL finished) {
                     // something
                 }];

// 不推荐
[UIView animateWithDuration:1.0 animations:^{
    // something 
} completion:^(BOOL finished) {
    // something
}];

关于换行

// 推荐
self.productsRequest = [[SKProductsRequest alloc] 
  initWithProductIdentifiers:productIdentifiers]; // 一行很长的代码在第二行以一个间隔（2个空格）延续

// 不推荐
self.productsRequest = [[SKProductsRequest alloc] initWithProductIdentifiers:productIdentifiers];

关于括号
1. 控制语句 (if-else, for, switch) 使用 Egyptian风格括号（又称 K&R 风格，代码段括号的开始位于一行的末尾，而不是另外起一行的风格。)
2. 类的实现和方法的实现不使用 Egyptian风格括号。

代码组织

利用代码块

代码块如果在闭合的圆括号内的话，会返回最后语句的值。

NSURL *url = ({
    NSString *urlString = [NSString stringWithFormat:@"%@/%@", baseURLString, endpoint];
    [NSURL URLWithString:urlString];
});

利用#pragma mark - 来分离。

- (void)dealloc { /* ... */ }
- (instancetype)init { /* ... */ }

#pragma mark - View Lifecycle （View 的生命周期）

- (void)viewDidLoad { /* ... */ }
- (void)viewWillAppear:(BOOL)animated { /* ... */ }
- (void)didReceiveMemoryWarning { /* ... */ }

#pragma mark - Custom Accessors （自定义访问器）

- (void)setCustomProperty:(id)value { /* ... */ }
- (id)customProperty { /* ... */ }

#pragma mark - IBActions  

- (IBAction)submitData:(id)sender { /* ... */ }

#pragma mark - Public 

- (void)publicMethod { /* ... */ }

#pragma mark - Private

- (void)zoc_privateMethod { /* ... */ }

#pragma mark - UITableViewDataSource

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath { /* ... */ }

#pragma mark - ZOCSuperclass

// ... 重载来自 ZOCSuperclass 的方法

#pragma mark - NSObject

- (NSString *)description { /* ... */ }

忽略没用使用变量的编译警告

- (NSInteger)giveMeFive
{
    NSString *foo;
    #pragma unused (foo)  // 注意，要标记到变量之后

    return 5;
}

明确编译器警告和错误

- (NSInteger)divide:(NSInteger)dividend by:(NSInteger)divisor
{
    #error Whoa, buddy, you need to check for zero here!
    return (dividend / divisor);
}

- (float)divide:(float)dividend by:(float)divisor
{
    #warning Dude, don't compare floating point numbers like this!
    if (divisor != 0.0) {
        return (dividend / divisor);
    }
    else {
        return NAN;
    }
}

字符串文档

短文档适用于单行的文件，包括注释斜杠。它适合简短的函数，特别是（但不仅仅是）非 public 的 API。
```
// Return a user-readable form of a Frobnozz, html-escaped.
```
如果描述超过一行，应改用长字符串文档：

以/**开始

换行写一句总结的话，以?或者!或者.结尾。

空一行

在与第一行对齐的位置开始写剩下的注释

最后用*/结束。
```
/**
 This comment serves to demonstrate the format of a docstring.

 Note that the summary line is always at most one line long, and
 after the opening block comment, and each line of text is preceded
 by a single space.
*/
```
一个函数必须有一个字符串文档，除非它符合下面的所有条件：

非公开

很短

显而易见

字符串文档应该描述函数的调用符号和语义，而不是它如何实现。

关于注释

头文档

一个类的文档应该只在 .h 文件里用 Doxygen/AppleDoc 的语法书写。方法和属性都应该提供文档。

/**
 *  Designated initializer.
 *
 *  @param  store  The store for CRUD operations.
 *  @param  searchService The search service used to query the store.
 *
 *  @return A ZOCCRUDOperationsStore object.
 */
- (instancetype)initWithOperationsStore:(id<ZOCGenericStoreProtocol>)store
                          searchService:(id<ZOCGenericSearchServiceProtocol>)searchService;

也就是说，当你定义一个类并且对外提供接口，那么需要在头文件中对这个类进行说明，并且对每一个属性/方法都要有明确的说明（使用上面提到的方式，用Doxygen/AppleDoc语法来书写注释。包括方法的参数，返回值等。）。而在实现文件中，如果一个方法/属性是简单，显而易见并且非公开的，那么可以不写注释，前提是保证让人一看就懂。

所有文章
【objc-zen-book】1.条件语句&Case语句的注意
 【objc-zen-book】2.命名
 【objc-zen-book】3.类
 【objc-zen-book】4.Category & NSNotification
【objc-zen-book】5.美化代码 & 代码组织
 【objc-zen-book】6.Block & self的循环引用

【objc-zen-book】5.美化代码 & 代码组织

美化代码

代码组织

推荐阅读更多精彩内容