前言
在一個應用的整個開發(fā)過程中涉及到了無數(shù)的步驟焕檬。其中一些是應用的說明 , 圖片的創(chuàng)作 , 應用的實現(xiàn) , 和實現(xiàn)過后的測試 . 寫代碼可能組成了這個過程的絕大部分 , 因為正是它給了應用生命 , 但是這樣還不夠 , 與它同等重要的還有代碼的注釋和文檔編寫 . 不管代碼寫的有多好 , 如果缺少了對應的好的注釋文檔 , 很有可能在將來帶來麻煩 . 不幸的是 , 許多開發(fā)者都忽視或忽略了代碼文檔的重要性 , 而這非常糟糕 , 因為好的程序不僅僅是好的代碼 . 它需要更多的東西.
對于注釋的重要性 這里我不再過多闡述 , 有興趣的話就看看下面引用的一段對注釋重要性的解釋:
談到編寫注釋文檔谎替，顯然我不是說僅僅簡單的在實現(xiàn)文檔里添加幾行注釋√ノВ肯定是更多的東西枝秤。但是首先俏扩，為什么對代碼進行注釋這么重要？好吧捕传，這里有兩個情景：不管你是單獨工作，或者你是團隊的一份子扩劝。讓我們來分別解釋一下庸论。
如果你是一個正在開發(fā)的應用的唯一開發(fā)者，有理由相信寫注釋文檔會消耗時間棒呛，所以忽略不做會讓你更迅速完成目標葡公。除此之外，很容易說服自己既然都是獨立開發(fā)者了沒有太大必要來做注釋文檔条霜。但是相信我催什，這將會是在應用開發(fā)期間做的最壞的決定。假設你成功的開發(fā)完成了應用宰睡，無論是在app store上銷售或者賣給你的客戶蒲凶，然后你把它保存起來。六個月后拆内，你必須要通過添加幾個新功能來創(chuàng)建一個這個應用的新版本旋圆。當你重新打開這個工程然后查看已有的代碼，在你寫下第一行新代碼之前一段時間麸恍，你會意識到一個殘酷的真相：你幾乎不記得任何東西灵巧！你做過什么搀矫，你怎么做的，為什么要這么做刻肄，都會很難回想起來瓤球！你必須通過一個痛苦的方法來在腦袋里重新喚起這個工程，這個方法就是從工程的最開始敏弃，一行行的“解密”你的實現(xiàn)代碼卦羡。僅僅是幾行注釋根本沒什么幫助，最終直到你理解所有東西之前會用很長的時間且花掉許多精力麦到。正在讀這些內(nèi)容的很大一部分的你們都可能遇到過那種情況绿饵，而且我很肯定的給你說過去我也遇到過。這種情況真的是噩夢一樣瓶颠，那時你經(jīng)常想干脆從頭開始做一個工程算了拟赊。當然，這里提到的場景可能僅僅會是一個...場景粹淋，只要我們花一點點時間來編寫合適的注釋文檔要门。
另一方面，如果你是團隊里的一員來開發(fā)工程廓啊，那么避開給代碼寫注釋文檔將會是災難性的欢搜。當你給其他開發(fā)者分享代碼時，你必須解釋你的觀點（在代碼里）谴轮，當時做了什么炒瘟，是怎樣做的，當然其他的開發(fā)者也被要求做同樣的事情第步。沒有一個情形是大項目的開發(fā)者們對后面開發(fā)者們開發(fā)的代碼都有全面的了解疮装，因為若是這樣，將會浪費掉很多不必要的時間粘都。因此廓推，在這種情況下的編寫注釋代碼一方面就像是做交流，另一方面也是幫助團隊里的其它開發(fā)者了解你的代碼的含義翩隧。畢竟樊展，每個程序員編寫代碼的風格都跟其他人不一樣，所以表達清楚你的代碼功能是件必須做的任務堆生。
概述
在開始之前 , 讓我說明兩件事情 . 第一专缠，我不是試圖讓你偏執(zhí)的寫文檔 , 而是說服你編寫合適的注釋將會提高你的編程生涯 . 第二 , 編寫代碼注釋文檔是你必須接受的習慣 , 而絕對不是浪費時間 .
注釋的使用說明
正如你知道的，在Objective-C 和 Swift中寫一條注釋的最簡單辦法是用兩條斜杠：
// 我是一條注釋.
你可以 (且必須) 像上面那樣來放置你的注釋 , 以便分清每個部分 . 但是 , 當談到代碼注釋文檔 , 我肯定不是指的上面的注釋 . 如果整個教程都專注于此肯定毫無意義 . 注釋文檔意味著以結(jié)構(gòu)化的方法使用特殊的關(guān)鍵字 , 也叫標簽來寫注釋 , 使用特殊的符號來標示注釋區(qū)域 , 因此編譯器可以完美的理解這個過程 . 只有一些簡單的規(guī)則需要遵守 . 上面操作的所有結(jié)果就是你的注釋文檔可以在三個不同的地方展示:
- 在Utilities面板的Quick Help Inspector 里.
- 當你按下Option鍵然后點擊方法 , 類或?qū)傩悦麜r彈出的幫助菜單 Help Popup 里.
- 在代碼實現(xiàn)彈出框里.
除此之外 , 合適的代碼注釋讓你可以使用眾多的工具來為你的應用創(chuàng)建完整的HTML文檔 , 例如the HeaderDoc 和 Doxygen . 它們兩個后面會提到.
當使用 Objective-C 寫代碼時有三種可能的方法來標示一個注釋文檔區(qū)域:
把你的注釋包含在/** 你的注釋 */ 塊里淑仆。
把你的注釋包含在 /*! 你的注釋 */塊里涝婉。
以三條斜杠 ///開始的注釋行
在這個教程實例中我們將會用第二種方法來寫我們的注釋文檔 . 我選擇它出于兩個原因 : 第一 , 它是唯一一個能被 HeaderDoc 識別的格式 , 而且如果注釋塊不是以它開頭 , 幫助頁也不會被生成 . 第二 , 盡管 Doxygen 更傾向于第一種格式 , 它也能識別第二種 . 因此 , 第二種格式將會在兩種方法下都適用 . 第三種格式通常在注釋一行時用到 , 例如屬性值時 , 因此 , 我們還是堅持用第二種格式.
現(xiàn)在 , 當寫注釋文檔時 , 你可以使用特定的關(guān)鍵值 (或標簽) . 標簽被分為兩個大類 : 第一個是 top level 標簽 , 它可以用來指定哪種類型的代碼被注釋了 , 例如類 , 結(jié)構(gòu)體 , 文件 , 等等 . 注意top level標簽不是必須使用，但是肯定會幫助導出工具 (例如 HeaderDoc 和 Doxygen) 創(chuàng)建出更好的結(jié)果 . 第二個是second level標簽 , 它指定了每個注釋文檔塊的細節(jié) . 這個類型的標簽正是你需要的 , 因為每一個都定義了另外的注釋文檔部分.
下面我給出了最重要的second level標簽 , 但是注意了這并不是全部 . 我們稍后會看到一些 top level標簽 . 我這里列出來的是最常用到的:
- @brief: 使用它來寫一段你正在文檔化的method, property , class , file , struct , 或enum的短描述信息.
- @discussion: 用它來寫一段詳盡的描述 . 如果需要你可以添加換行 .
- @param: 通過它你可以描述一個 method 或 function的參數(shù)信息 . 你可以使用多個這種標簽.
- @return: 用它來制定一個 method 或 function的返回值.
- @see: 用它來指明其他相關(guān)的 method 或 function . 你可以使用多個這種標簽.
- @sa: 同前一條類似.
- @code: 使用這個標簽 , 你可以在文檔當中嵌入代碼段 . 當在Help Inspector當中查看文檔時 , 代碼通過在一個特別的盒子中用一種不同的字體來展示 . 始終記住在寫的代碼結(jié)尾處使用@endcode標簽.
- @remark:在寫文檔時蔗怠，用它來強調(diào)任何關(guān)于代碼的特殊之處.
你可以在 這里 （HeaderDoc User Guide）找到包含所有支持的標簽的列表.
注意 : @符號是每個標簽的前綴 . 同樣 , 你也可以在文本中使用特殊字符switches , 這樣就可以改變它的類型和格式墩弯。例如吩跋，Text 以會讓 Text單詞成為黑體，同時Text也會讓 Text 單詞的類型為italic. 有趣的是你也可以把部分文本以代碼形式展現(xiàn)（不是代碼段）渔工，如果寫下@cText锌钮，當幫助文檔在Xcode上展現(xiàn)時，它會導致展示一個不同的字體格式涨缚。
除開上面說的 , 你也可以替換@符號為反斜杠(\) . 那樣的話標簽就會像這樣被展示： \brief, \param, \return,等等 . 注意反斜杠最常在 Doxyten 文檔系統(tǒng)里面被使用 , 而@符號常在 HeaderDoc 里面被使用 . 在這里我們會在所有地方使用@ , 因為它在兩個系統(tǒng)中都通用.
注釋的使用演示
屬性:
讓我們看看以上我提到的內(nèi)容是怎樣使用的 . 首先我聲明一個屬性:
@property (nonatomic , copy ) NSString *name;
然后如下面所示添加注釋文檔:
/*! @brief 用戶姓名屬性 */
@property (nonatomic , copy ) NSString *name;
然后到這個類某一個方法中 , 開始輸入這個屬性 . 你將看到在代碼填充彈出框里我們剛剛寫下的注釋就在那里了.
而且不僅這樣 . 當在鍵盤上按住 Option 鍵，點擊name屬性就會讓幫助窗口彈出：
更多的 , 如果在Utilities面板打開 Help Inspector , 你會在那里找到相同的文檔.
注意在上面的注釋當中 @brief 標簽可以被去掉而不會導致任何問題 . 意味著下面的這條注釋也是有效的:
/*! 用戶姓名屬性 */
@property (nonatomic , copy ) NSString *name;
同樣的策治，下面的也一樣:
/** 用戶姓名屬性 */
@property (nonatomic , copy ) NSString *name;
而且下面的這條也一樣:
/// 用戶姓名屬性 */
@property (nonatomic , copy ) NSString *name;
方法:
我來演示一下方法注釋的示例 , 那么只是公有方法（在頭文件里的）的文檔是可見的 . 無論你在類的私有部分中寫的任何文檔在 Xcode 幫助文檔里都是可見的 , 但是任何實現(xiàn)部分都沒有被導出到注釋文檔里 . 所以 , 記住這些 , 現(xiàn)在讓我們在LaunchViewController.h 文件里定義一個公有方法:
- (NSString *)stringToMD5:(NSString *)fromString;
很顯然 , 這個方法將會把一個字符串轉(zhuǎn)換為MD5加密的 . 現(xiàn)在我們來添加注釋文檔:
/*!
* @brief MD5加密字符串
*
* @discussion 傳入一個字符串對象 并通過MD5加密算法對其進行 16位加密
*
* @param fromString為要加密的字符串對象
*
* @return 16位小寫加密字符串
*/
- (NSString *)stringToMD5:(NSString *)fromString;
注意在上面我們使用HTML開關(guān)來讓所有包含的文字分別是粗體和斜體脓魏。同樣注意我們是怎樣使用@c開關(guān)來標識內(nèi)嵌代碼
接下來我們這在ViewController.m文件中實現(xiàn)這個方法:
#pragma mark - MD5加密字符串
- (NSString *)stringToMD5:(NSString *)fromString{
const char *cStr = [fromString UTF8String];
unsigned char result[CC_MD5_DIGEST_LENGTH];
CC_MD5(cStr, (CC_LONG)strlen(cStr), result);
return [[NSString stringWithFormat:@"%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X%02X",
result[0], result[1], result[2], result[3],
result[4], result[5], result[6], result[7],
result[8], result[9], result[10], result[11],
result[12], result[13], result[14], result[15]
] lowercaseString];
}
同樣我們把光標放到方法名上，在Quick Help Inspector里查看：
方法中調(diào)用這個函數(shù) , 那么就可以在函數(shù)自動填充窗口里看到簡介描述:
很棒 , 是不是 ? 可以想象你的代碼那樣文檔化后會變得多有幫助 且能自我解釋清楚代碼意義 , 特別是當你同其他團隊人員一起工作時.
下面我們玩點有意思的 , 為這個注釋增加點更直觀的效果:
沒錯 代碼框 和 備注 , 通過@code - @endcode標簽 和 @remark標簽 可以讓我們的自己的文檔注釋和Xcode默認文檔比起來毫不遜色.
在前面部分我們?yōu)g覽了寫屬性或方法時需要遵守的記錄文檔規(guī)則 . 我故意從屬性和方法開始介紹編寫文檔 , 因為你的大部分開發(fā)時間都是消耗在那里⊥ū梗現(xiàn)在我們已經(jīng)看到了最主要的部分 , 現(xiàn)在繼續(xù)看看怎樣對 files , classes , structs 和 enums 添加注釋.
讓我們從files開始 , 怎樣在Objective-C中寫下能提供信息的文檔 . 當同其他人分享編程工作時 , 或者當你以開放源代碼組件形式分發(fā)代碼時 , 那么添加file documentation就是必須的 , 因為這是最佳的地方來向你的開發(fā)伙伴或者使用你代碼的人提供明確的信息 . 通常 , 你將要更關(guān)注header 文件 (.h) 以及在它里面的描述信息 , 因為這些會保留在將被導出的最終文檔里 (并不在Xcode里) ; 但是 , 這并不代表你不需要在implementation文件中添加描述信息 . 不要忘記當在Xcode中打開工程時 , 所有的東西都在那兒 , 不僅僅是header 文件 , 因此保證你不會留下沒被記錄文檔的部分 . 除此之外 , 實現(xiàn)部分不會在導出文檔中看到 , 但是所有文件的描述信息始終都是可見的.
文件:
讓我介紹一些當你在記錄一個文件時會用到的新標簽:
- @file: 使用這個標簽來指出你正在記錄一個文件 (header 文件或不是) . 如果你將使用Doxygen來輸出文檔 , 那么你最好在這個標簽后面緊接著寫上文件名字 . 它是一個top level 標簽.
- @header: 跟上面的類似 , 但是是在 HeaderDoc中使用 . 當你不使用 Doxygen時 , 不要使用上面的標簽.
- @author: 用它來寫下這個文件的創(chuàng)建者信息.
- @copyright: 添加版權(quán)信息.
- @version: 用它來寫下這個文件的當前版本 , 如果在工程生命周期中版本信息有影響時這會很重要.
當然你還可以使用更多的標簽 , 但是這些都是最常使用的一部分 . 我建議你通覽HeaderDoc 或 the Doxygen文檔 , 這樣就可以發(fā)現(xiàn)一些額外的你想使用的關(guān)鍵字.
現(xiàn)在我們來看對LaunchViewController.h 頭文件添加注釋 . 找到文件的開頭 , 就在import 命令之前 . 在那里添加下面的幾行：
/*!
* @header LaunchViewController.h
*
* @brief 啟動視圖控制器,在程序啟動時加載顯示
*
* @author LEE
* @copyright ? 2016年 lee. All rights reserved.
* @version 16.3.3
*/
你可以把 LEE 替換成你自己的名字或者公司的名字 . 同樣的 , 使用 brief標簽而不省略它是很好的習慣 , 因為它會讓文檔系統(tǒng) (在HeaderDoc 和 Doxygen中稍后將會看到) 在輸出的HTML網(wǎng)頁上展示你在這兒添加的簡短描述 . 我再提醒一次 , 在Doxygen里你可以使用反斜杠來代替“@”茂翔。同樣的 , 在這里你將不會看到剛才說的文檔長什么樣 , 但是我們將會在后續(xù)輸出HTML文件時展示.
以上的都很棒 , 但是實事卻是在大多數(shù)情況下 , 你創(chuàng)建的新文件里由Xcode自動添加的提供信息的默認注釋都非常好而且夠用了 . 當你在團隊里同其他人一起協(xié)作 , 并且每個成員必須描述清楚他負責的那些文件的細節(jié)信息時 , 或者當你打算使用 HeaderDoc 或 Doxygen來輸出一個工程的完整文檔時 , 又或者當你是獨立開發(fā)者但是工程擁有數(shù)量眾多的文件時 , 你可能想創(chuàng)建一個文件描述塊 . 不管怎樣 , 由你自己決定你的文檔系統(tǒng)需要完善到哪個level.
類:
讓我們來看看怎樣對class或者protocol寫注釋文檔 . 再一次的 , 我只給出最常用的標簽 . 自己查看說明文檔了解更多標簽信息.
- @class: 用它來指定一個class的注釋文檔塊的開頭 . 它是一個top level標簽 . 在它后面應該給出class名字.
- @interface: 同上.
- @protocol: 同上兩個一樣 , 只是針對protocols.
- @superclass: 當前class的superclass.
- @classdesign: 用這個標簽來指出你為當前class使用的任何特殊設計模式 (例如 , 你可以提到這個class是不是單例模式或者類似其它的模式).
- @coclass: 與當前class合作的另外一個class的名字.
- @helps: 當前class幫助的class的名字.
- @helper: 幫助當前class的class名字.
實際上 , 可能除了superclass你幾乎很少用到上面的標簽 . 可用標簽的列表很長 , 只是我覺得在這里列出更多沒太大意義 . 必須指出的是從superclass開始以及下面的所有標簽 , 都不能被 Doxygen識別 , 只能被HeaderDoc識別 . 同樣的 , 在Xcode里的 Quick Help 和 Help Popup 彈出框里展示的是各個標簽旁邊的值 , 而不會展示標簽本身 . 因此 , 用不用他們?nèi)Q于你是否使用文檔系統(tǒng)以及使用哪一個.
/*!
* @class LaunchViewController
*
* @brief 啟動視圖控制器類
*
* @superclass SuperClass: UIViewController
* @classdesign 視圖控制器基類
* @coclass AppDelegate
* @helps 不幫助其他類
* @helper 無幫助類
*/
@interface LaunchViewController : UIViewController
協(xié)議:
按照上面的方法也可以對protocol添加注釋 . 在LaunchViewController.h 文件開頭添加下面的幾行:
/*!
* @protocol ViewControllerDelegate
*
* @brief 啟動視圖控制器協(xié)議
*/
@protocol LaunchViewControllerDelegate
/*!
* 啟動視圖控制器已經(jīng)消失
*/
-(void)launchViewControllerDidDisappear;
可以看到在上面 , 我們也聲明了一個delegate 方法 . 可能此刻你覺得那毫無意義 , 但是我故意把它放在這里是作為示例demo ; 當我們使用 HeaderDoc 和 Doxygen 來導出文檔時就會在導出的頁面看到它了.
結(jié)構(gòu)體:
現(xiàn)在我們討論了files,classes 和protocols 希望你有了一個大概的了解，現(xiàn)在看看一些特殊示例：怎樣對structs 和 enumerations進行注釋履腋。它們的共同點是在兩個當中都使用 @typedef top level 標簽珊燎，以此來標示注釋塊的開始（再次提醒使用top level 完全自愿）。
特別是對于Doxygen系統(tǒng)遵湖，不使用@typedef標簽悔政，你應該對structs使用@struct 標簽，對enums使用@enum標簽延旧。
讓我們看以下的代碼谋国。把它添加到LaunchViewController.h 文件的interface之前：
typedef struct {
int type;
float time;
BOOL isShowImage;
} LaunchConfig;
現(xiàn)在把下面的注釋添加在它前面:
/*!
* @typedef LaunchConfig
*
* @brief 啟動設置.
*
* @discussion 啟動視圖控制器會根據(jù)此結(jié)構(gòu)體內(nèi)的變量值實現(xiàn)相應的操作.
*
* @field launchType 啟動類型
* @field launchTime 啟動視圖控制器顯示時間
* @field isShowImage 是否顯示圖片
*/
typedef struct {
int launchType;
float launchTime;
BOOL isShowImage;
} LaunchConfig;
可以看到 , 出現(xiàn)了一個名叫 @field 的新標簽 . 這個標簽的目的是對struct里面的每一個變量進行描述 . 再次 , 我必須強調(diào) HeaderDoc 和 Doxygen 的不同之處 . 在 HeaderDoc 里 , 這個標簽是可接受且有效的 . 但是 , 在 Doxygen 里卻不是這樣 . 在這個案例里我們做的僅僅是分開對每一個變量進行注釋 . 這樣做會使當我們在 implementation 文件里使用它們時能展示出每個的注釋 . 我們來看看吧 (注意標簽和變量上方的注釋有著不同的值 , 所以在后面會更輕松的區(qū)別出來):
/*!
* @struct LaunchConfig
*
* @brief 啟動設置.
*
* @discussion 啟動視圖控制器會根據(jù)此結(jié)構(gòu)體內(nèi)的變量值實現(xiàn)相應的操作.
*
* @field launchType 啟動類型
* @field launchTime 啟動視圖控制器顯示時間
* @field isShowImage 是否顯示圖片
*/
typedef struct {
/*! 啟動類型 */
int launchType;
/*! 啟動視圖控制器顯示時間 */
float launchTime;
/*! 是否顯示圖片 */
BOOL isShowImage;
} LaunchConfig;
如果現(xiàn)在到 LaunchViewController.m 文件中定義一個這個struct的變量 , 無論輸入以上任何變量的一個都會在彈出窗口里看到它的描述.
Enumerations也是同樣的 , 所以我把它作為練習留給你自己去創(chuàng)建一個enum類型然后進行注釋 . 非常簡單 , 是不是 ? 當enum創(chuàng)建好后 , 到viewDidLoad方法里去查看它的注釋會不會在Xcode的幫助選項里展示出來.
錯誤提示
在先前的例子里可以看到 , 在 @param 標簽旁必須寫出變量名字 , 之后才是描述信息 . 當然 , 誤輸入一個變量名 , 特別是當它有些復雜時 , 以及創(chuàng)建的文檔包含錯誤都是很有可能的 . 但是 , 有個方法可以避免這種情況發(fā)生 , 我猜你可能并不知道Xcode可以在這時成為你的可靠助手.
盡管Xcode在文檔開始寫時就處理了 , 它也可以幫助你避免誤輸入任何變量名 . 只要開啟一個配置就能讓它做到這點 . 讓我們來看看我到底想表達的是什么:
在 Project Navigator里 , 點擊工程 , 找到Build Settings標簽 , 在搜索框里輸入comments關(guān)鍵字然后等待下方給出的結(jié)果 . 其中一個結(jié)果就是名為Documentation Comments的配置 , 通常它的默認值是NO . 你做的僅僅是把它的值設為YES , 一切就緒 . 如下圖所示:
設置好后 , 我們舉個例子來演示一下效果.
就拿我們之前的寫好的示例代碼來說 , 我將注釋中 @param 標簽后面的參數(shù)名故意寫錯 , 大家可以看到 Xcode為我們彈出了警告:
這時候你點擊黃色的警告三角 , 就會看到Xcode為你自動推薦了正確的變量名 , 你可以繼續(xù)點擊它就會幫你自動修復 , 當然你也可以自己去修改.
有了上面的這些 , 麻麻再也不需要擔心在寫文檔時誤輸入任何變量名了.
總結(jié)
上面說了這么多相信你已經(jīng)對文檔注釋有了更多的了解 , 想象一下 當你在使用別人的庫做開發(fā)時 , 調(diào)用某些方法 你可能并不知道這個方法是做什么的 , 但是當代碼填充框內(nèi)的注釋出現(xiàn)時 , 是不是心里暗爽呢 ? 因為你不需要再花額外的時間去做了解 , 換位思考 , 當別人在使用你的代碼時 , 也可以獲得相同的便利 , 豈不是兩全其美嗎 ?
之前我們有提到兩個工具 Doxygen 和 HeaderDoc , 其中有一些注釋標簽的使用也是根據(jù)這兩個做了很多說明 . 如果你想繼續(xù)了解注釋文檔的生成 , 那么請繼續(xù)閱讀__注釋文檔 __, 在這里你會了解到如何使用不同工具來生成屬于自己的注釋文檔.
我是LEE , 如果你還有更好的建議 歡迎給我留言 , 如果喜歡記得點贊喲 ! 么了個噠~
注: 本篇文章主要參考自AppCoda.
