有了這些你們團隊的程式碼肯定規範

杭城小劉發表於2019-03-04

最近重構專案元件，看到專案中存在一些命名和方法分塊方面存在一些問題，結合平時經驗和 Apple官方程式碼規範在此整理出 iOS 工程規範。提出第一個版本，如果後期覺得有不完善的地方，繼續提出來不斷完善，文件在此記錄的目的就是為了大家的程式碼可讀性較好，後來的人或者團隊裡面的其他人看到程式碼可以不會因為程式碼風格和可讀性上面造成較大時間的開銷。

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

一些原則

長的，描述性的方法和變數命名是好的。不要使用簡寫，除非是一些大家都知道的場景比如 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

類的註釋

有時候我們需要為我們建立的類設定一些註釋。我們可以在類的下面新增。

列舉

列舉的命名和類的命名相近。

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 之後空一格，括號，裡面的執行緒修飾詞、記憶體修飾詞、讀寫修飾詞，空一格類物件名稱 根據不同的場景選擇合適的修飾符。

@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 掉。

單例的使用場景概括如下：

控制資源的使用，通過執行緒同步來控制資源的併發訪問。
控制例項的產生，以達到節約資源的目的。
控制資料的共享，在不建立直接關聯的條件下，讓多個不相關的程式或執行緒之間實現通訊。

+ (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 的響應事件都放在這個區域裡面，不要到處亂放。

檔案基本上就是

//___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等的檔案模版的存放資料夾地址後，我們就可以設想下我們是否可以定製自己團隊風格的控制器模版、是否可以打造和維護自己團隊的高頻使用的程式碼塊？

答案是可以的。

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_型別 開頭，Enter鍵自動補全。比如 Strong 型別，編寫程式碼通過 Property_Strong Enter鍵自動補全成如下格式
```
@property (nonatomic, strong) <#Class#> *<#object#>;
複製程式碼
```
方法：以 Method_關鍵詞 Enter鍵確認，自動補全。比如 Method_UIScrollViewDelegate Enter鍵自動補全成如下格式
```
#pragma mark - UIScrollViewDelegate
- (void)scrollViewDidScroll:(UIScrollView *)scrollView {
    
}
複製程式碼
```
各種常見的 Mark：以 Mark_關鍵詞 回車確認，自動補全。比如 Method_MethodsGroup Enter鍵自動補全成如下格式
```
#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 //將本地的程式碼塊和檔案模版同步到雲端
複製程式碼

PS

不斷完善中。大家有好用或者不錯的程式碼塊或者檔案模版希望參與到這個專案中來，為我們開發效率的提升添磚加瓦、貢獻力量

目前新建了大概58個程式碼段和6個類檔案模版（UIViewController控制器帶有方法組、模型、執行緒安全的單例模版、帶有佈局方法的UIView模版、UITableViewCell、UICollectionViewCell模版）

shell 指令碼基本有每個函式和關鍵步驟的程式碼註釋，想學習 shell 的人可以看看程式碼。程式碼傳送門

Vue eslint 團隊程式碼規範
2019-04-20
VueEsLint
打造高效小團隊 - 團隊程式碼提交流程 && 規範
2019-12-11
iOS團隊編碼規範
2017-12-14
iOS
iOS 團隊程式設計規範
2017-08-22
iOS程式設計
這些Python程式碼技巧，你肯定還不知道
2018-09-04
Python
團隊程式碼規範 ESLint + Prettier + EditorConfig
2022-01-25
EsLint
公司最近來了個實習生——我要哭了，同學們請收好你們的程式碼規範！！！！！程式碼不規範，親人兩行淚
2020-06-11
一些常用的程式碼規範
2021-11-03
excalidraw 這些用法你肯定不瞭解
2024-07-21
關於Objective C編碼規範，這些你一定要會
2019-04-18
Object
團隊專案的Git分支管理規範
2019-06-18
Git
建立合格的跨職能團隊，你需要知道這些！
2021-11-30
iOS專案自動程式碼風格規範化--團隊協作的福音
2018-02-22
iOS
使用git_hooks庫助力Flutter團隊編碼規範
2021-03-15
GitHookFlutter
搜狐視訊iOS團隊 Objective-C 編碼規範
2018-08-07
iOSObject
如果你寫了25年程式碼，你將會遇到這些
2015-12-15
系統整容紀：揭秘Java程式設計之美：掌握這些編碼規範，讓你的程式碼一躍成為行業典範
2024-07-23
Java程式設計行業
過年，你肯定會用到這款小程式！
2018-02-10
CSS你可以不寫，但這些規範必須要知道！
2019-05-07
CSS
初為程式猿(媛)的你，這些技能可以為你們加持
2017-08-27
團隊分享，Bem規範調研及實踐
2021-12-07
【敏捷開發】Android團隊開發規範
2014-03-23
敏捷Android
前端工程化（2）：快速搭建基於angular團隊程式碼提交規範的工作流
2019-03-27
前端Angular
求求你規範下你的程式碼風格
2019-01-24
PHP 規範 - Symfony 程式碼規範
2019-11-06
PHP
這樣的微信商城原始碼，你肯定沒見過。
2019-05-11
原始碼
這樣規範寫程式碼，同事直呼“666”
2020-04-06
程式設計師想要月薪2W+？這些能力你有了嗎？
2019-12-04
程式設計師
[譯] 這些 CSS 命名規範將省下你大把除錯時間
2018-01-29
CSS除錯
java程式碼規範有什麼意義
2020-01-06
Java
iOS程式猿這些工具你值得擁有
2016-06-23
iOS
有了這25個正規表示式，程式碼效率提高80%
2021-11-20
Android 程式碼規範 - 命名規範
2017-04-09
Android
Android程式碼規範：命名規範
2016-07-07
Android
搭建Typescript+React專案模板(5) — 團隊規範
2019-03-02
TypeScriptReact
搭建Typescript+React專案模板(5) --- 團隊規範
2018-09-27
TypeScriptReact
程式碼規範之前端編寫碼規範
2020-10-20
前端
谷歌用兩年時間研究了 180 個團隊，發現高效團隊有這五個特徵
2017-08-23
谷歌特徵