有了這些大家團隊的代碼確定規範

時間 2019-11-06

標籤有了這些大家團隊代碼確定規範简体版

原文原文鏈接

最近重構項目組件，看到項目中存在一些命名和方法分塊方面存在一些問題，結合平時經驗和 Apple官方代碼規範在此整理出 iOS 工程規範。提出第一個版本，若是後期以爲有不完善的地方，繼續提出來不斷完善，文檔在此記錄的目的就是爲了你們的代碼可讀性較好，後來的人或者團隊裏面的其餘人看到代碼能夠不會由於代碼風格和可讀性上面形成較大時間的開銷。html

軟件的生命週期貫穿產品的開發，測試，生產，用戶使用，版本升級和後期維護等過程，只有易讀，易維護的軟件代碼才具備生命力。
複製代碼

一些原則

長的，描述性的方法和變量命名是好的。不要使用簡寫，除非是一些你們都知道的場景好比 VIP。不要使用 bgView，推薦使用 backgroundView
見名知意。含義清楚，作好不加註釋代碼自我表述能力強。（前提是代碼足夠規範）
不要過度追求技巧，下降代碼可讀性
刪除不必的代碼。好比咱們新建一個控制器，裏面會有一些不會用到的代碼，或者註釋起來的代碼，若是這些代碼不須要，那就刪除它，留着偷懶嗎？下次須要本身手寫
在方法內部不要重複計算某個值，適當的狀況下能夠將計算結果緩存起來
儘可能減小單例的使用。
提供一個統一的數據管理入口，不論是 MVC、MVVM、MVP 模塊內提供一個統一的數據管理入口會使得代碼變得更容易管理和維護。
除了 .m 文件中方法，其餘的地方"{"不須要另起一行。

- (void)getGooodsList
{
    // ...
}

- (void)doHomework
{
    if (self.hungry) {
        return;
    }
    if (self.thirsty) {
        return;
    }
    if (self.tired) {
        return;
    }
    papapa.then.over;
}
複製代碼

變量

一個變量最好只有一個做用，切勿爲了節省代碼行數，以爲一個變量能夠作多個用途。（單一原則）
方法內部若是有局部變量，那麼局部變量應該靠近在使用的地方，而不是所有在頂部聲明所有的局部變量。

運算符

1元運算符和變量之間不須要空格。例如：++n
2元運算符與變量之間須要空格隔開。例如： containerWidth = 0.3 * Screen_Width
當有多個運算符的時候須要使用括號來明確正確的順序，可讀性較好。例如： 2 << (1 + 2 * 3 - 4)

條件表達式

當有條件過多、過長的時候須要換行，爲了代碼看起來整齊些

//good
if (condition1() && 
    condition2() && 
    condition3() && 
    condition4()) {
  // Do something
}
//bad
if (condition1() && condition2() && condition3() && condition4(）) { // Do something }
複製代碼

在一個代碼塊裏面有個可能的狀況時善於使用 return 來結束異常的狀況。

- (void)doHomework
{
    if (self.hungry) {
        return;
    }
    if (self.thirsty) {
        return;
    }
    if (self.tired) {
        return;
    }
    papapa.then.over;
}
複製代碼

每一個分支的實現都必須使用 {} 包含。

// bad
if (self.hungry) self.eat() 
// good
if (self.hungry) {
    self.eat()
}
複製代碼

條件判斷的時候應該是變量在左，條件在右。 if ( currentCursor == 2 ) { //... }
switch 語句後面的每一個分支都須要用大括號括起來。
switch 語句後面的 default 分支必須存在，除非是在對枚舉進行 switch。

switch (menuType) {  
  case menuTypeLeft: {
    // ...  
    break; 
   }
  case menuTypeRight: {
    // ...  
    break; 
  }
  case menuTypeTop: {
    // ...  
    break; 
  }
  case menuTypeBottom: {
    // ...  
    break; 
  }
}
複製代碼

類名

大寫駝峯式命名。每一個單詞首字母大寫。好比「申請記錄控制器」ApplyRecordsViewController
每一個類型的命名以該類型結尾。
- ViewController：使用 ViewController 結尾。例子：ApplyRecordsViewController
- View：使用 View 結尾。例子：分界線：boundaryView
- NSArray：使用 s 結尾。好比商品分類數據源。categories
- UITableViewCell：使用 Cell 結尾。好比 MyProfileCell
- Protocol：使用 Delegate 或者 Datasource 結尾。好比 XQScanViewDelegate
- Tool：工具類
- 代理類：Delegate
- Service 類：Service

類的註釋

有時候咱們須要爲咱們建立的類設置一些註釋。咱們能夠在類的下面添加。git

枚舉

枚舉的命名和類的命名相近。github

typedef NS_ENUM(NSInteger, UIControlContentVerticalAlignment) {
    UIControlContentVerticalAlignmentCenter  = 0,
    UIControlContentVerticalAlignmentTop     = 1,
    UIControlContentVerticalAlignmentBottom  = 2,
    UIControlContentVerticalAlignmentFill    = 3,
};
複製代碼

宏

所有大寫，單詞與單詞之間用 _ 鏈接。
以 K 開頭。後面遵循大寫駝峯命名。「不帶參數」

#define HOME_PAGE_DID_SCROLL @"com.xq.home.page.tableview.did.scroll"
#define KHomePageDidScroll @"com.xq.home.page.tableview.did.scroll"
複製代碼

屬性

書寫規則，基本上就是 @property 以後空一格，括號，裏面的線程修飾詞、內存修飾詞、讀寫修飾詞，空一格類對象名稱 根據不一樣的場景選擇合適的修飾符。objective-c

@property (nonatomic, strong) UITableView *tableView;
@property (nonatomic, assign, readonly) BOOL loading;   
@property (nonatomic, weak) id<#delegate#> delegate;
@property (nonatomic, copy) <#returnType#> (^<#Block#>)(<#parType#>);
複製代碼

單例

單例適合全局管理狀態或者事件的場景。一旦建立，對象的指針保存在靜態區，單例對象在堆內存中分配的內存空間只有程序銷燬的時候纔會釋放。基於這種特色，那麼咱們相似 UIApplication 對象，須要全局訪問惟一一個對象的狀況才適合單例，或者訪問頻次較高的狀況。咱們的功能模塊的生命週期確定小於 App 的生命週期，若是多個單例對象的話，勢必 App 的開銷會很大，糟糕的狀況系統會殺死 App。若是以爲非要用單例比較好，那麼注意須要在合適的場合 tearDown 掉。shell

單例的使用場景歸納以下：緩存

控制資源的使用，經過線程同步來控制資源的併發訪問。
控制實例的產生，以達到節約資源的目的。
控制數據的共享，在不創建直接關聯的條件下，讓多個不相關的進程或線程之間實現通訊。

+ (instancetype)sharedInstance
{
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        //because has rewrited allocWithZone  use NULL avoid endless loop lol.
        _sharedInstance = [[super allocWithZone:NULL] init];
    });
    
    return _sharedInstance;
}

+ (id)allocWithZone:(struct _NSZone *)zone
{
    return [TestNSObject sharedInstance];
}

+ (instancetype)alloc
{
    return [TestNSObject sharedInstance];
}

- (id)copy
{
    return self;
}

- (id)mutableCopy
{
    return self;
}

- (id)copyWithZone:(struct _NSZone *)zone
{
    return self;
}

複製代碼

私有變量

推薦以 _ 開頭，寫在 .m 文件中。例如 NSString * _somePrivateVariable安全

代理方法

類的實例必須做爲方法的參數之一。
對於一些連續的狀態的，能夠加一些 will（將要）、did（已經）
以類的名稱開頭

- (void)tableView:(UITableView *)tableView willDisplayCell:(UITableViewCell *)cell forRowAtIndexPath:(NSIndexPath *)indexPath;

- (void)tableView:(UITableView *)tableView didEndDisplayingCell:(UITableViewCell *)cell forRowAtIndexPath:(NSIndexPath *)indexPath;
複製代碼

方法

方法與方法之間間隔一行
大量的方法儘可能要以組的形式放在一塊兒，好比生命週期函數、公有方法、私有方法、setter && getter、代理方法..
方法最後面的括號須要另起一行。遵循 Apple 的規範
對於其餘場景的括號，括號不須要單獨換行。好比 if 後面的括號。
若是方法參數過多過長，建議多行書寫。用冒號進行對齊。
一個方法內的代碼最好保持在50行之內，通常經驗來看若是一個方法裏面的代碼行數過多，代碼的閱讀體驗就不好（別問爲何，作太重構代碼行數很長的人都有相似的心情）
一個函數只作一個事情，作到單一原則。全部的類、方法設計好後就能夠相似搭積木同樣實現一個系統。
對於有返回值的函數，且函數內有分支狀況。確保每一個分支都有返回值。
函數若是有多個參數，外部傳入的參數須要檢驗參數的非空、數據類型的合法性，參數錯誤作一些措施：當即返回、斷言。
多個函數若是有邏輯重複的代碼，建議將重複的部分抽取出來，成爲獨立的函數進行調用

- (instancetype)init
{
    self = [super init];
    if (self) {
        <#statements#>
    }
    return self;
}

- (void)doHomework:(NSString *)name
            period:(NSInteger)second
            score:(NSInteger)score;
複製代碼

方法若是有多個參數的狀況下須要注意是否須要介詞和連詞。不少時候在不知道如何抉擇測時候思考下蘋果的一些 API 的方法命名。

//good
- (instancetype)initWithAge:(NSInteger)age name:(NSString *)name;

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath;


//bad
- (instancetype)initWithAge:(NSInteger)age andName:(NSString *)name;

- (void)tableView:(UITableView *)tableView :(NSIndexPath *)indexPath;
複製代碼

.m 文件中的私有方法須要在頂部進行聲明
方法組之間也有個順序問題。

在文件最頂部實現屬性的聲明、私有方法的聲明（不少人省去這一步，問題不大，可是蠻多第三方的庫都寫了，看起來仍是會很方便，建議書寫）。
在生命週期的方法裏面，好比 viewDidLoad 裏面只作界面的添加，而不是作界面的初始化，全部的 view 初始化建議放在 getter 裏面去作。每每 view 的初始化的代碼長度會比較長、且通常會有多個 view 因此 getter 和 setter 通常建議放在最下面，這樣子頂部就能夠很清楚的看到代碼的主要邏輯。
全部button、gestureRecognizer 的響應事件都放在這個區域裏面，不要處處亂放。

文件基本上就是bash

//___FILEHEADER___

#import "___FILEBASENAME___.h"
/*ViewController*/

/*View&&Util*/

/*model*/

/*NetWork InterFace*/

/*Vender*/

@interface ___FILEBASENAMEASIDENTIFIER___ ()

@end

@implementation ___FILEBASENAMEASIDENTIFIER___


#pragma mark - life cycle
- (void)viewWillAppear:(BOOL)animated
{
    [super viewDidAppear:animated];
}

- (void)viewDidAppear:(BOOL)animated
{
    [super viewDidAppear:animated];
    
}

- (void)viewDidLoad
{
    [super viewDidLoad];
    self.title = <#value#>;
}

- (void)viewWillDisappear:(BOOL)animated
{
    [super viewDidAppear:animated];
    
}

- (void)viewDidDisappear:(BOOL)animated
{
    [super viewDidAppear:animated];
    
}

#ifdef DEBUG
- (void)dealloc
{
    NSLog(@"%s",__func__);
}
#endif

#pragma mark - public Method

#pragma mark - private method

#pragma mark - event response



#pragma mark - UITableViewDelegate

#pragma mark - UITableViewDataSource
//...(多個代理方法依次往下寫)

#pragma mark - getters and setters

@end
複製代碼

圖片資源

單個文件的命名文件資源的命名也須要必定的規範，形式爲：功能模塊名_類別_功能_狀態@nx.png Setting_Button_search_selected@2x.png、Setting_Button_search_selected@3x.png Setting_Button_search_unselected@2x.png、Setting_Button_search_unselected@3x.png
資源的文件夾命名最好也參考 App 按照功能模塊創建對應的實體文件夾目錄，最後到對應的目錄下添加相應的資源文件。

註釋

對於類的註釋寫在當前類文件的頂部
對於屬性的註釋須要寫在屬性後面的地方。 //**<userId*/
對於 .h 文件中方法的註釋，一概按快捷鍵 command+option+/。三個快捷鍵解決。按需在旁邊對方法進行說明解釋、返回值、參數的說明和解釋
對於 .m 文件中的方法的註釋，在方法的旁邊添加 //。
註釋符和註釋內容須要間隔一個空格。例如： // fetch goods list

版本規範

採用 A.B.C 三位數字命名，好比：1.0.2，當有更新的狀況下按照下面的依據併發

版本號	右說明對齊標題	示例
A.b.c	屬於重大內容的更新	1.0.2 -> 2.0.0
a.B.c	屬於小部份內容的更新	1.0.2 -> 1.1.1
a.b.C	屬於補丁更新	1.0.2 -> 1.0.3

改進

咱們知道了平時在使用 Xcode 開發的過程當中使用的系統提供的代碼塊所在的地址和新建控制器、模型、view等的文件模版的存放文件夾地址後，咱們就能夠設想下咱們是否能夠定製本身團隊風格的控制器模版、是否能夠打造和維護本身團隊的高頻使用的代碼塊？app

答案是能夠的。

Xcode 代碼塊的存放地址：~/Library/Developer/Xcode/UserData/CodeSnippets Xcode 文件模版的存放地址：/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/File Templates/

意義

爲了我的或者團隊開發者的代碼更加規範。Property的書寫的時候的空格、線程修飾詞、內存修飾詞的前後順序
提供大量可用的代碼塊，提升開發效率。好比在 Xcode 裏面敲 UITableView_init 即可以自動懶加載建立一個 UITabelView 對象，你只須要設置在指定的位置寫相應的參數
經過一些代碼塊提升代碼規範、避免一些bug。好比曾看到過 block 屬性用 strong 修飾的代碼，形成內存泄漏。舉個例子你在 Xcode 中輸入 Property_delegate 就會出來 @property (nonatomic, weak) id<<#delegate#>> delegate;，你輸入 Property_block 就會出來 @property (nonatomic, copy) <#returnType#> (^<#Block#>)(<#parType#>);

代碼塊的改造

咱們能夠將屬性、控制器生命週期方法、單例構造一個對象的方法、代理方法、block、GCD、UITableView 懶加載、UITableViewCell 註冊、UITableView 代理方法的實現、UICollectionVIew 懶加載、UICollectionVIewCell 註冊、UICollectionView 的代理方法實現等等組織爲 codesnippets

思考

封裝好 codesnippets 以後團隊除了你編寫這個項目的人如何使用？如何知道是否有這個代碼塊？

方案：先在團隊內召開代碼規範會議，你們都統一知道這個事情在。以後你們共同維護 codesnippets。用法見下

屬性：經過 Property_類型 開頭，回車鍵自動補全。好比 Strong 類型，編寫代碼經過 Property_Strong 回車鍵自動補全成以下格式
```
@property (nonatomic, strong) <#Class#> *<#object#>;
複製代碼
```
方法：以 Method_關鍵詞 回車鍵確認，自動補全。好比 Method_UIScrollViewDelegate 回車鍵自動補全成以下格式
```
#pragma mark - UIScrollViewDelegate
- (void)scrollViewDidScroll:(UIScrollView *)scrollView {
    
}
複製代碼
```
各類常見的 Mark：以 Mark_關鍵詞 回車確認，自動補全。好比 Method_MethodsGroup 回車鍵自動補全成以下格式
```
#pragma mark - life cycle
#pragma mark - public Method
#pragma mark - private method
#pragma mark - event response
#pragma mark - UITableViewDelegate
#pragma mark - UITableViewDataSource
#pragma mark - getters and setters
複製代碼
```
封裝好 codesnippets 以後團隊內如何統一？想到一個方案，能夠將團隊內的 codesnippets 共享到 git，團隊內的其餘成員再從雲端拉取同步。這樣的話團隊內的每一個成員均可以使用最新的 codesnippets 來編碼。

編寫 shell 腳本。幾個關鍵步驟：
1. 給系統文件夾受權
2. 在腳本所在文件夾新建存放代碼塊的文件夾
3. 將系統文件夾下面的代碼塊複製到步驟2建立的文件夾下面
4. 將當前的全部文件提交到 Git 倉庫

文件模版的改造

咱們觀察系統文件模版的特色，和在 Xcode 新建文件模版對應。

因此咱們新建 Custom 文件夾，將系統 Source 文件夾下面的 Cocoa Touch Class.xctemplate 複製到 Custom 文件夾下。重命名爲咱們須要的名字，我這裏以「Power」爲例

進入 PowerViewController.xctemplate/PowerViewControllerObjective-C

修改 ___FILEBASENAME___.h 和 ___FILEBASENAME___.m 文件內容

在替換 .h 文件內容的時候後面改成 UIViewController，否則其餘開發者新建文件模版的時候出現的不是 UIViewController 而是咱們的 PowerViewController

修改 TemplateInfo.plist

思考：

如何使用

商量好一個標識（「Power」）。好比我新建了單例、控制器、Model、UIView、UITableViewCell、UICollectionViewCell6個模版，都覺得 Power 開頭。
如何共享

以 shell 腳本爲工具。使用腳本將 git 雲端的代碼模版同步到本地 Xcode 文件夾對應的位置就可使用了。關鍵步驟：
1. git clone 代碼到腳本所在文件夾
2. 進入存放 codesnippets 的文件夾將內容複製到系統存放 codesnippets 的地方
3. 進入存放 file template 的文件夾將內容複製到系統存放 file template 的地方

內容及其如何使用

Property 屬性。敲 Property_ 自動聯想，光標移動選中後敲回車自動補全
Mark 標識。敲 Mark_ 自動聯想，會展現各類經常使用的 Mark，光標移動選中後敲回車自動補全
Method 方法。敲 Method_ 自動聯想，會展現各類經常使用的 Method，光標移動選中後敲回車自動補全
GCD。敲 GCD_ 自動聯想，會展現各類經常使用的 GCD，光標移動選中後敲回車自動補全
經常使用 UI 控件的懶加載。敲 _init 自動聯想，展現經常使用的 UI 控件的懶加載，光標移動選中後敲回車自動補全
Delegate。敲 Delegate_ 自動聯想，會展現各類經常使用的 Delegate，光標移動選中後敲回車自動補全
Notification。敲 NSNotification_ 自動聯想，會展現各類經常使用的 NSNotification 的代碼塊，好比發送通知、添加觀察者、移除觀察者、觀察者方法的實現等等，光標移動選中後敲回車自動補全
Protocol。敲 Protocol_ 自動聯想，會展現各類經常使用的 Protocol 的代碼塊，光標移動選中後敲回車自動補全
內存修飾代碼塊
工程經常使用 TODO、FIXME、Mark。敲 Mark_ 自動聯想，會展現各類經常使用的 Mark 的代碼塊，光標移動選中後敲回車自動補全
內存修飾代碼塊。敲 Memory_ 自動聯想，會展現各類經常使用的內存修飾的代碼塊，光標移動選中後敲回車自動補全
一些經常使用的代碼塊。敲 Thread_ 等自動聯想，選中後敲回車自動補全。

使用

chmod +x ./syncSnippets.sh // 爲腳本設置可執行權限
chmod +x ./uploadMySnippets.sh // 爲腳本設置可執行權限
./syncSnippets.sh // 同步git雲端代碼塊和文件模版到本地
./uploadMySnippets.sh //將本地的代碼塊和文件模版同步到雲端
複製代碼