google objective-c coding style(3)注釋

標籤：

注釋

雖然寫起來很痛苦，但注釋是保證代碼可讀性的關鍵。下面的規則給出了你應該什麼時候、在哪進行注釋。記住：儘管注釋很重要，但最好的代碼應該自成文檔。與其給類型及變數起一個晦澀難懂的名字，再為它寫注釋，不如直接起一個有意義的名字。

當你寫注釋的時候，記得你是在給你的聽眾寫，即下一個需要閱讀你所寫代碼的貢獻者。大方一點，下一個讀代碼的人可能就是你！

記住所有 C++ 風格指南裡的規則在這裡也同樣適用，不同的之處後續會逐步指出。

檔案注釋

Tip

每個檔案的開頭以檔案內容的簡要描述起始，緊接著是作者，最後是著作權聲明和/或許可證樣板。

著作權資訊及作者

每個檔案應該按順序包括如下項：

• 檔案內容的簡要描述
• 代碼作者
• 著作權資訊聲明（如：Copyright 2008 Google Inc.）
• 必要的話，加上許可證樣板。為項目選擇一個合適的授權樣板（例如，Apache 2.0, BSD, LGPL, GPL）。

如果你對其他人的原始代碼作出重大的修改，請把你自己的名字添加到作者裡面。當另外一個代碼貢獻者對檔案有問題時，他需要知道怎麼聯絡你，這十分有用。

聲明部分的注釋

Tip

每個介面、類別以及協議應輔以注釋，以描述它的目的及與整個項目的關係。

// A delegate for NSApplication to handle notifications about app// launch and shutdown. Owned by the main app controller.@interface MyAppDelegate : NSObject {  ...}@end

如果你已經在檔案頭部詳細描述了介面，可以直接說明 “完整的描述請參見檔案頭部”，但是一定要有這部分注釋。

另外，公用介面的每個方法，都應該有注釋來解釋它的作用、參數、傳回值以及其它影響。

為類的執行緒安全性作注釋，如果有的話。如果類的執行個體可以被多個線程訪問，記得注釋多線程條件下的使用規則。

實現部分的注釋

Tip

使用 | 來引用注釋中的變數名及符號名而不是使用引號。

這會避免二義性，尤其是當符號是一個常用詞彙，這使用語句讀起來很糟糕。例如，對於符號 count ：

// Sometimes we need |count| to be less than zero.

或者當引用已經包含引號的符號：

// Remember to call |StringWithoutSpaces("foo bar baz")|

對象所有權

Tip

當與 Objective-C 最常規的作法不同時，盡量使指標的所有權模型盡量明確。

繼承自 NSObject 的對象的執行個體變數指標，通常被假定是強參考關聯性（retained），某些情況下也可以注釋為弱引用（weak）或使用 __weak 生命週期限定符。同樣，聲明的屬性如果沒有被類 retained，必須指定是弱引用或賦予 @property 屬性。然而，Mac 軟體中標記上 IBOutlets 的執行個體變數，被認為是不會被類 retained 的。

當執行個體變數指向 CoreFoundation、C++ 或者其它非 Objective-C 對象時，不論指標是否會被 retained，都需要使用 __strong 和 __weak 類型修飾符明確指明。CoreFoundation 和其它非 Objective-C 對象指標需要顯式的記憶體管理，即便使用了自動引用計數或記憶體回收機制。當不允許使用 __weak 類型修飾符（比如，使用 clang 編譯時間的 C++ 成員變數），應使用注釋替代說明。

注意：Objective-C 對象中的 C++ 對象的自動封裝，預設是不允許的，參見 這裡 的說明。

強引用及弱引用聲明的例子：

@interface MyDelegate : NSObject { @private  IBOutlet NSButton *okButton_;  // normal NSControl; implicitly weak on Mac only  AnObjcObject* doohickey_;  // my doohickey  __weak MyObjcParent *parent_;  // so we can send msgs back (owns me)  // non-NSObject pointers...  __strong CWackyCPPClass *wacky_;  // some cross-platform object  __strong CFDictionaryRef *dict_;}@property(strong, nonatomic) NSString *doohickey;@property(weak, nonatomic) NSString *parent;@end

（譯註：強引用 - 對象被類 retained。弱引用 - 對象沒有被類 retained，如委託）

google objective-c coding style(3)注釋