注釋

2018-02-24 15:12 更新

雖然寫起來(lái)很痛苦,但注釋是保證代碼可讀性的關(guān)鍵。下面的規(guī)則給出了你應(yīng)該什么時(shí)候、在哪進(jìn)行注釋。記?。罕M管注釋很重要,但最好的代碼應(yīng)該自成文檔。與其給類型及變量起一個(gè)晦澀難懂的名字,再為它寫注釋,不如直接起一個(gè)有意義的名字。

當(dāng)你寫注釋的時(shí)候,記得你是在給你的聽眾寫,即下一個(gè)需要閱讀你所寫代碼的貢獻(xiàn)者。大方一點(diǎn),下一個(gè)讀代碼的人可能就是你!

記住所有 C++ 風(fēng)格指南里的規(guī)則在這里也同樣適用,不同的之處后續(xù)會(huì)逐步指出。

文件注釋

Tip

每個(gè)文件的開頭以文件內(nèi)容的簡(jiǎn)要描述起始,緊接著是作者,最后是版權(quán)聲明和/或許可證樣板。

版權(quán)信息及作者

每個(gè)文件應(yīng)該按順序包括如下項(xiàng):

  • 文件內(nèi)容的簡(jiǎn)要描述
  • 代碼作者
  • 版權(quán)信息聲明(如:Copyright 2008 Google Inc.
  • 必要的話,加上許可證樣板。為項(xiàng)目選擇一個(gè)合適的授權(quán)樣板(例如,Apache 2.0, BSD, LGPL, GPL)。

如果你對(duì)其他人的原始代碼作出重大的修改,請(qǐng)把你自己的名字添加到作者里面。當(dāng)另外一個(gè)代碼貢獻(xiàn)者對(duì)文件有問(wèn)題時(shí),他需要知道怎么聯(lián)系你,這十分有用。

聲明部分的注釋

Tip

每個(gè)接口、類別以及協(xié)議應(yīng)輔以注釋,以描述它的目的及與整個(gè)項(xiàng)目的關(guān)系。

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

如果你已經(jīng)在文件頭部詳細(xì)描述了接口,可以直接說(shuō)明 “完整的描述請(qǐng)參見文件頭部”,但是一定要有這部分注釋。

另外,公共接口的每個(gè)方法,都應(yīng)該有注釋來(lái)解釋它的作用、參數(shù)、返回值以及其它影響。

為類的線程安全性作注釋,如果有的話。如果類的實(shí)例可以被多個(gè)線程訪問(wèn),記得注釋多線程條件下的使用規(guī)則。

實(shí)現(xiàn)部分的注釋

Tip

使用 | 來(lái)引用注釋中的變量名及符號(hào)名而不是使用引號(hào)。

這會(huì)避免二義性,尤其是當(dāng)符號(hào)是一個(gè)常用詞匯,這使用語(yǔ)句讀起來(lái)很糟糕。例如,對(duì)于符號(hào) count

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

或者當(dāng)引用已經(jīng)包含引號(hào)的符號(hào):

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

對(duì)象所有權(quán)

Tip

當(dāng)與 Objective-C 最常規(guī)的作法不同時(shí),盡量使指針的所有權(quán)模型盡量明確。

繼承自 NSObject 的對(duì)象的實(shí)例變量指針,通常被假定是強(qiáng)引用關(guān)系(retained),某些情況下也可以注釋為弱引用(weak)或使用 __weak 生命周期限定符。同樣,聲明的屬性如果沒(méi)有被類 retained,必須指定是弱引用或賦予 @property 屬性。然而,Mac 軟件中標(biāo)記上 IBOutlets 的實(shí)例變量,被認(rèn)為是不會(huì)被類 retained 的。

當(dāng)實(shí)例變量指向 CoreFoundation、C++ 或者其它非 Objective-C 對(duì)象時(shí),不論指針是否會(huì)被 retained,都需要使用 __strong__weak 類型修飾符明確指明。CoreFoundation 和其它非 Objective-C 對(duì)象指針需要顯式的內(nèi)存管理,即便使用了自動(dòng)引用計(jì)數(shù)或垃圾回收機(jī)制。當(dāng)不允許使用 __weak 類型修飾符(比如,使用 clang 編譯時(shí)的 C++ 成員變量),應(yīng)使用注釋替代說(shuō)明。

注意:Objective-C 對(duì)象中的 C++ 對(duì)象的自動(dòng)封裝,缺省是不允許的,參見 這里 [http://chanson.livejournal.com/154253.html] 的說(shuō)明。

強(qiáng)引用及弱引用聲明的例子:

@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

(譯注:強(qiáng)引用 - 對(duì)象被類 retained。弱引用 - 對(duì)象沒(méi)有被類 retained,如委托)

以上內(nèi)容是否對(duì)您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號(hào)
微信公眾號(hào)

編程獅公眾號(hào)