iOS項目OC代碼規範 -> 純文本規範

代碼規範

目的是爲了組內代碼風格統一，增強代碼的可讀性以及方便維護。這裏只作一些非技術方面的代碼約束要求。這裏大概是參照了AFNetworking以及FaceBook開源代碼作了一些tip級別的約束。

Tip1 關於註釋

註釋是爲了說明一個代碼模塊或者代碼段。好比你在github上丟一塊代碼給你們用。那麼就須要你的用戶在沒有你的狀況下可以經過你的註釋用好用對你的代碼。

哪些地方該寫註釋

我的認爲該寫註釋的點有SDK類好比網絡層、數據倉庫、工具類。而像咱們常常打交道的VC我以爲寫好段註釋足矣，在一些比較黑魔法以及比較複雜的業務邏輯寫好該寫上的註釋便可！

怎麼寫

這裏拿了AF的框架來作模板：

文件註釋結構以下：

1. 概述 @abstract （可能等價於）

2. 詳述 @discussion

3. 注意 @warning

屬性註釋以下：

大概描述下幹啥用，以及是否有默認值，使用注意事項好比值的範圍之類的。

接口註釋以下：

主要仍是參數說明，返回值說明，使用注意事項以及特殊的一些聲明。

對於大部分的ViewController.m文件，我的認爲只要寫好段註釋，比如ViewLifecycle、DataSource/Delegate，Actions，IB Methods。以及在關鍵地方，好比業務邏輯比較複雜或者容易引發Crash的地方須要引發注意的地方補上註釋。

Tip2 關於常量

用const代替define
主要緣由是會define編譯器不會幫忙作一層檢查。可能在運行時遇到一些Crash！
const使用在.m中對將要使用的一些常量包括字符串，整型，浮點數甚至是結構體進行聲明初始化，好比：

這裏補充一點是宏定義仍是有使用場景的，好比說斷言，或者代碼段好比判斷iOS版本，好比判斷設備類型這種，用宏的主要緣由是偷懶，可是須要放在一個文件內作維護，這兒要你們統一維護否則就呵呵了。。

Tip3 關於代碼風格

我以爲這點每一個寫的習慣不同可是做爲一個Team寫的習慣相似一點我以爲仍是有點好處的。咱們用的是OC，你們知道OC的特色是變量名又臭又長（美其名是說自解釋性）。問題來了就是如何進行空格以及大小括號怎麼放還有何時多敲一個回車的問題，這裏盜點文章：

關於在哪裏空格

麻了吉就一個字：在關鍵字後面留空格，在逗號（符號）以後留空格

關於在哪裏回車

Preferred:

// blocks are easily readable
[UIView animateWithDuration:1.0 animations:^{
  // something
} completion:^(BOOL finished) {
  // something
}];

Not Preferred:

// colon-aligning makes the block indentation hard to read
[UIView animateWithDuration:1.0
                 animations:^{
                     // something
                 }
                 completion:^(BOOL finished) {
                     // something
                 }];

緣由就是OC代碼又臭又長，你還冒號對齊，你看代碼的時候很容易看飛了，而括號對齊能保證代碼不容易看飛！

關於寫好一個正常的API接口

Preferred:

- (void)setExampleText:(NSString *)text image:(UIImage *)image;
- (void)sendAction:(SEL)aSelector to:(id)anObject forAllCells:(BOOL)flag;
- (id)viewWithTag:(NSInteger)tag;
- (instancetype)initWithWidth:(CGFloat)width height:(CGFloat)height;

Not Preferred:

-(void)setT:(NSString *)text i:(UIImage *)image;
- (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;
- (id)taggedView:(NSInteger)tag;
- (instancetype)initWithWidth:(CGFloat)width andHeight:(CGFloat)height;
- (instancetype)initWith:(int)width and:(int)height;  // Never do this.

哥們麻煩放點正常API好很差。一個正常API大概就是漢語裏面的主謂賓。還有及物動詞不及物動詞。。不及物動次記得加上介詞。。。。

關於if else應該怎麼接

Preferred:

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

Not Preferred:

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

緣由仍是由於OC代碼相對比較長，這麼寫結構性更好一點。這個組內達成一個標準就行了。

關於如何在代碼塊中留回車

這裏拿的是AF框架作的一個說明，mattt的代碼規範我我的仍是很推崇的。

Tip4 關於集合類

Preferred:

NSArray *names = @[@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul"];
NSDictionary *productManagers = @{@"iPhone": @"Kate", @"iPad": @"Kamal", @"Mobile Web": @"Bill"};
NSNumber *shouldUseLiterals = @YES;
NSNumber *buildingStreetNumber = @10018;

Not Preferred:

NSArray *names = [NSArray arrayWithObjects:@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul", nil];
NSDictionary *productManagers = [NSDictionary dictionaryWithObjectsAndKeys: @"Kate", @"iPhone", @"Kamal", @"iPad", @"Bill", @"Mobile Web", nil];
NSNumber *shouldUseLiterals = [NSNumber numberWithBool:YES];
NSNumber *buildingStreetNumber = [NSNumber numberWithInteger:10018];

第一種寫法的好處仍是簡單明瞭，並且代碼更簡潔！
字典聲明的時候仍是應當寫的更人性化一點好比：

NSDictionary *productManagers = @{
                                  @"iPhone": @"Kate", 
                                  @"iPad": @"Kamal", 
                                  @"Mobile Web": @"Bill"
                                  };

Tip5 關於OC中的結構體及其屬性

我相信不少人喜歡這麼寫：

CGRect frame = self.view.frame;

CGFloat x = frame.origin.x;
CGFloat y = frame.origin.y;
CGFloat width = frame.size.width;
CGFloat height = frame.size.height;

這樣寫固然OK了，可是看上去代碼很累贅，更傾向這種寫法：

CGFloat x = CGRectGetMinX(frame);
CGFloat y = CGRectGetMinY(frame);
CGFloat width = CGRectGetWidth(frame);
CGFloat height = CGRectGetHeight(frame);

多用點C函數可使代碼整潔點。

RW的代碼規範中強調了不該該使用結構體聲明，其實我以爲挺好，好比：

CGRect frame = (CGRect){ 
                        .origin = CGPointZero, 
                        .size = frame.size 
                        };
CGPoint point = (CGPoint){ 
                          .x = 5, 
                          .y = 6 
                          };

我不以爲這種賦值影響可讀性。。我以爲可讀性會好一點吧....

Tip6 關於段註釋

我的不太喜歡在.m中寫太多的註釋，由於我以爲ViewController中的代碼分段大概都是類似的。
這裏仍是給出AF的段註釋來給說明：

#pragma mark -

這個只是一個分割線的效果，通常一個文件有多個@implementation的時候使用

#pragma mark - 段索引

這個是分割線帶了概述
截個AF的圖來講明：

這是說下概述特麼不是亂寫的，正確的概述寫法在按住CMD鍵鼠標左鍵點擊的時候是能夠進行跳轉的，規範標準仍是以可以跳轉爲主！

Tip7 關於告警

麻了吉一個字不要留告警，採起任何的手段把告警去掉。。。由於實在看的難受。。。。不要吐槽哥。。

#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wassign-enum"
        if (alpha == kCGImageAlphaNone) {
            bitmapInfo &= ~kCGBitmapAlphaInfoMask;
            bitmapInfo |= kCGImageAlphaNoneSkipFirst;
        } else if (!(alpha == kCGImageAlphaNoneSkipFirst || alpha == kCGImageAlphaNoneSkipLast)) {
            bitmapInfo &= ~kCGBitmapAlphaInfoMask;
            bitmapInfo |= kCGImageAlphaPremultipliedFirst;
        }
#pragma clang diagnostic pop

其餘去除告警的關鍵字（"-Wassign-enum"）請谷歌。。。去掉告警的時候有必要請同步組內成員！