【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

---

美化代码

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

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

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

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

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

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

5. 关于换行

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

6. 关于括号

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

代码组织

1. 利用代码块

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

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

2. 利用#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 { /* ... */ }
   

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

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

4. 明确编译器警告和错误

   - (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;
       }
   }
   

5. 字符串文档

   短文档适用于单行的文件，包括注释斜杠。它适合简短的函数，特别是（但不仅仅是）非 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.
   */
   

   一个函数必须有一个字符串文档，除非它符合下面的所有条件：

   非公开

   很短

   显而易见

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

6. 关于注释

   头文档

   一个类的文档应该只在 .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)store
                             searchService:(id)searchService;
   

7. 也就是说，当你定义一个类并且对外提供接口，那么需要在头文件中对这个类进行说明，并且对每一个属性/方法都要有明确的说明（使用上面提到的方式，用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的循环引用

​