代碼組織

代碼組織

來自 Mattt Thompson

code organization is a matter of hygiene (代碼組織是衛(wèi)生問題)

我們十分贊成這句話。清晰地組織代碼和規(guī)范地進行定義, 是你對自己以及其他閱讀代碼的人的尊重。

利用代碼塊

一個 GCC 非常模糊的特性，以及 Clang 也有的特性是，代碼塊如果在閉合的圓括號內(nèi)的話，會返回最后語句的值

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

這個特性非常適合組織小塊的代碼，通常是設(shè)置一個類。他給了讀者一個重要的入口并且減少相關(guān)干擾，能讓讀者聚焦于關(guān)鍵的變量和函數(shù)中。此外，這個方法有一個優(yōu)點，所有的變量都在代碼塊中，也就是只在代碼塊的區(qū)域中有效，這意味著可以減少對其他作用域的命名污染。

Pragma

Pragma Mark

#pragma mark - 是一個在類內(nèi)部組織代碼并且?guī)椭惴纸M方法實現(xiàn)的好辦法。 我們建議使用 #pragma mark - 來分離:

• 不同功能組的方法
• protocols 的實現(xiàn)
• 對父類方法的重寫

- (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 { /* ... */ }

上面的標記能明顯分離和組織代碼。你還可以用 cmd+Click 來快速跳轉(zhuǎn)到符號定義地方。 但是小心，即使 paragma mark 是一門手藝，但是它不是讓你類里面方法數(shù)量增加的一個理由：類里面有太多方法說明類做了太多事情，需要考慮重構(gòu)了。

關(guān)于 pragma

在 http://raptureinvenice.com/pragmas-arent-just-for-marks 有很好的關(guān)于 pragma 的討論了，在這邊我們再做部分說明。

大多數(shù) iOS 開發(fā)者平時并沒有和很多編譯器選項打交道。一些選項是對控制嚴格檢查（或者不檢查）你的代碼或者錯誤的。有時候，你想要用 pragma 直接產(chǎn)生一個異常，臨時打斷編譯器的行為。

當你使用ARC的時候，編譯器幫你插入了內(nèi)存管理相關(guān)的調(diào)用。但是這樣可能產(chǎn)生一些煩人的事情。比如你使用 NSSelectorFromString 來動態(tài)地產(chǎn)生一個 selector 調(diào)用的時候，ARC不知道這個方法是哪個并且不知道應(yīng)該用那種內(nèi)存管理方法，你會被提示 performSelector may cause a leak because its selector is unknown（執(zhí)行 selector 可能導致泄漏，因為這個 selector 是未知的）.

如果你知道你的代碼不會導致內(nèi)存泄露，你可以通過加入這些代碼忽略這些警告

#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Warc-performSelector-leaks"

[myObj performSelector:mySelector withObject:name];

#pragma clang diagnostic pop

注意我們是如何在相關(guān)代碼上下文中用 pragma 停用 -Warc-performSelector-leaks 檢查的。這確保我們沒有全局禁用。如果全局禁用，可能會導致錯誤。

全部的選項可以在 The Clang User's Manual 找到并且學習。

忽略沒用使用變量的編譯警告

這對表明你一個定義但是沒有使用的變量很有用。大多數(shù)情況下，你希望移除這些引用來（稍微地）提高性能，但是有時候你希望保留它們。為什么？或許它們以后有用，或者有些特性只是暫時移除。無論如何，一個消除這些警告的好方法是用相關(guān)語句進行注解，使用 #pragma unused():

- (void)giveMeFive
{
    NSString *foo;
    #pragma unused (foo)

    return 5;
}

現(xiàn)在你的代碼不用任何編譯警告了。注意你的 pragma 需要標記到未定義的變量之下。

明確編譯器警告和錯誤

編譯器是一個機器人，它會標記你代碼中被 Clang 規(guī)則定義為錯誤的地方。但是，你總是比 Clang 更聰明。通常，你會發(fā)現(xiàn)一些討厭的代碼 會導致這個問題，而且不論怎么做，你都解決不了。你可以這樣明確一個錯誤：

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

字符串文檔

所有重要的方法，接口，分類以及協(xié)議定義應(yīng)該有伴隨的注釋來解釋它們的用途以及如何使用。更多的例子可以看 Google 代碼風格指南 File and Declaration Comments。

簡而言之：有長的和短的兩種字符串文檔。

短文檔適用于單行的文件，包括注釋斜杠。它適合簡短的函數(shù)，特別是（但不僅僅是）非 public 的 API：

// Return a user-readable form of a Frobnozz, html-escaped.

文本應(yīng)該用一個動詞 ("return") 而不是 "returns" 這樣的描述。

如果描述超出一行，你應(yīng)該用長的字符串文檔: 一行斜杠和兩個星號來開始塊文檔 (/**, 之后是總結(jié)的一句話，可以用句號、問號或者感嘆號結(jié)尾，然后空一行，在和第一句話對齊寫下剩下的注釋，然后用一個 (*/)來結(jié)束。

/**
 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.
*/

一個函數(shù)必須有一個字符串文檔，除非它符合下面的所有條件：

• 非公開
• 很短
• 顯而易見

字符串文檔應(yīng)該描述函數(shù)的調(diào)用符號和語義，而不是它如何實現(xiàn)。

注釋

當它需要的時候，注釋應(yīng)該用來解釋特定的代碼做了什么。所有的注釋必須被持續(xù)維護或者干脆就刪除。

塊注釋應(yīng)該被避免，代碼本身應(yīng)該盡可能就像文檔一樣表示意圖，只需要很少的打斷注釋 例外： 這不能適用于用來產(chǎn)生文檔的注釋

頭文檔

一個類的文檔應(yīng)該只在 .h 文件里用 Doxygen/AppleDoc 的語法書寫。 方法和屬性都應(yīng)該提供文檔。

例子:

/**
 *  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;