最全最詳細(xì)的注釋使用說(shuō)明

[TOC]

前言

• 好的代碼本身就是一種注釋
• 代碼的可讀性更重要

注釋的作用

代碼的意義，除了完成功能業(yè)務(wù)這一最基本的要求之外倔约，最終還要讓別人能夠讀懂你的代碼纱注，讓別人看得懂這段邏輯的意義共郭，讓別人更快更準(zhǔn)確的理解這個(gè)方法的使用規(guī)則，同時(shí)使代碼層級(jí)分明府喳，方便快速瀏覽脖卖，以及生成使用文檔等等∏删保總之就是方便自己與他人后期維護(hù)畦木。尤其是多人維護(hù)同一個(gè)項(xiàng)目的時(shí)候，注釋的意義不言而喻砸泛，注釋到位十籍，別人去維護(hù)你寫(xiě)的代碼時(shí)，就不會(huì)那么頻繁的問(wèn)你唇礁，甚至背后問(wèn)候你了~~~

常用的注釋分類

個(gè)人理解勾栗，對(duì)于注釋的分類，從宏觀功能上劃分盏筐，可以分為 代碼注釋 和 特殊功能注釋围俘。
代碼注釋又可以從位置特點(diǎn)上細(xì)分，可以分為單行注釋琢融，行尾注釋（多用于屬性界牡、枚舉值），多行注釋（方法漾抬，協(xié)議宿亡，類等）。
下面我將從剛剛說(shuō)的幾個(gè)維度去介紹纳令。

環(huán)境介紹

• demo日期：2019.1.1
• macOS 10.14.1
• Xcode 10.1
• 示例代碼語(yǔ)言：Objective-C

代碼注釋

需要寫(xiě)代碼注釋的地方非常多挽荠，包括不限于以下場(chǎng)景：文件的注釋克胳、類的注釋、一段代碼邏輯的說(shuō)明圈匆；屬性漠另、枚舉、方法臭脓、block等聲明的注釋

單行注釋

最常見(jiàn)的就是這下面這樣樣式：

示例代碼：

/* 這個(gè)方法的功能是做這個(gè)事情的酗钞，要注意呀~ */
+ (void)method {
    // 這里邏輯是這樣的，要注意呀~
    [self new];
}

/// 單行注釋10
@property (nonatomic, copy) NSString *str10;
//! 單行注釋11
@property (nonatomic, copy) NSString *str11;
/** 單行注釋12-可用于多行 */
@property (nonatomic, copy) NSString *str12;
/*! 單行注釋13-可用于多行 */
@property (nonatomic, copy) NSString *str13;

上面兩種注釋方法来累，都是最最常見(jiàn)的普通注釋的寫(xiě)法砚作，兩種寫(xiě)法但凡是寫(xiě)注釋的地方都能用上，能夠滿足注釋最基本的提示功能嘹锁，沒(méi)有什么特別要說(shuō)明的葫录。不過(guò)有一個(gè)缺陷是不會(huì)有 [option + 單擊] 時(shí)Xcode的注釋提示，所以和下面的單行注釋分開(kāi)說(shuō)领猾。

使用場(chǎng)景大多是代碼塊中米同，對(duì)于一些邏輯關(guān)鍵的的描述。另外摔竿，個(gè)人比較喜歡前后都加上一個(gè)空格的寫(xiě)法面粮。

后面四種寫(xiě)法無(wú)論是否加空格，使用上都沒(méi)有區(qū)別继低，都會(huì)有Xcode補(bǔ)全時(shí)的提示熬苍，以及 [option + 單擊] 時(shí)的提示。

總之袁翁，單行注釋適合無(wú)入?yún)⑦壿嫼?jiǎn)單的 類柴底、方法、block 等的注釋粱胜。
也可以用于屬性或枚舉的注釋柄驻，不過(guò)，屬性枚舉注釋個(gè)人認(rèn)為更適合用行尾注釋焙压。

行尾注釋

行尾最大的特點(diǎn)鸿脓，就是在三個(gè)注釋符號(hào)加上一個(gè)<小于號(hào)緊密的湊在一起。

示例代碼：

@property (nonatomic, copy) NSString *str20; ///< 行尾注釋20
@property (nonatomic, copy) NSString *str21; //!< 行尾注釋21
@property (nonatomic, copy) NSString *str22; /**< 行尾注釋22 */
@property (nonatomic, copy) NSString *str23; /*!< 行尾注釋23 */

個(gè)人覺(jué)得行尾注釋使用場(chǎng)景最多在于屬性的聲明和枚舉值定義涯曲，這時(shí)候這么寫(xiě)一行就展示的下答憔，屏幕大的時(shí)候看代碼清晰明了。

有幾個(gè)注意點(diǎn)（對(duì)于屬性和枚舉）：

• 所有上述寫(xiě)法掀抹，無(wú)論是否帶空格虐拓，無(wú)論是在.h或.m中，Xcode代碼補(bǔ)全時(shí)會(huì)有提示
• 在.h中傲武，四種寫(xiě)法都能 [option + 單擊] 顯示方法注釋
• 在.m中蓉驹，只有 [///<不帶空格] 這種注釋寫(xiě)法點(diǎn)擊才會(huì)顯示注釋

也就是說(shuō)城榛，[///<不帶空格] 這種注釋寫(xiě)法是最簡(jiǎn)單有效的行尾注釋寫(xiě)法。不過(guò)态兴，我總覺(jué)得不帶空格總是不夠優(yōu)雅~

行尾注釋不能適用于單行注釋狠持，否則和最最普通的注釋無(wú)差別。

另外瞻润，如果屬性含義過(guò)于復(fù)雜喘垂，尤其是存在多種狀態(tài)時(shí)，可以使用多行注釋的寫(xiě)法绍撞。

多行注釋

示例代碼：

手動(dòng)寫(xiě)的樣式：

/**
 *  方法注釋test02
 */
- (void)test02 {}
/*!
 *  方法注釋test03
 */
- (void)test03 {}

Xcode生成的樣式：

/**
 這是一個(gè)多參數(shù)的方法
 
 @param count   參數(shù)0正勒，數(shù)量
 @param str     參數(shù)1，字符串
 @param objc    參數(shù)2傻铣，對(duì)象
 @return        返回值章贞，返回值bool情況說(shuō)明
 */
- (BOOL)testC0WithCount:(NSUInteger)count str:(NSString *)str objc:(id)objc {
    return YES;
}

效果如圖：

方法option提示-01.png

上面兩種沒(méi)有什么好說(shuō)了，具體就是看個(gè)人喜好與團(tuán)隊(duì)風(fēng)格了非洲。下面說(shuō)一下各個(gè)關(guān)鍵字的使用鸭限。

參數(shù)list：

注釋中常用的標(biāo)簽：

/**
 *  各種關(guān)鍵字的使用示例

 @brief 使用它來(lái)寫(xiě)一段你正在文檔化的method, PRoperty, class, file, struct, 或enum的短描述信息超歌。
 @discusstion 參數(shù)用它來(lái)寫(xiě)一段詳盡的描述。如果需要你可以添加換行蒂教。
 我換兩行試試
 第三行呢巍举？
 
 
 @param str 參數(shù)
 @return        返回值，返回值bool情況說(shuō)明

 @note 注意點(diǎn)凝垛，補(bǔ)充說(shuō)明

 @see - (BOOL)testC0WithCount:(NSUInteger)count str:(NSString *)str objc:(id)objc{}
 @sa 同上

 @code
    使用這個(gè)標(biāo)簽懊悯，你可以在文檔當(dāng)中嵌入代碼段蜓谋。當(dāng)在Help Inspector當(dāng)中查看文檔時(shí)，代碼通過(guò)在一個(gè)特別的盒子中用一種不同的字體來(lái)展示炭分。始終記住在寫(xiě)的代碼結(jié)尾處使用標(biāo)簽
    // 方法
     - (void)testb0 {
        NSLog(@"注釋標(biāo)簽");
     }
 @endcode
 
 @remark 在寫(xiě)文檔時(shí)桃焕，用它來(lái)強(qiáng)調(diào)任何關(guān)于代碼的特殊之處。
 
 *  其他注釋
 */
- (BOOL)testC1WithParam:(NSString *)str {
    return NO;
}

效果如圖：

方法option提示-02.png

附加：

記錄文件常用標(biāo)簽：

特殊功能注釋

特殊功能注釋展示效果通常都是在類的方法list中撇吞，也就是 [ctrl + 6] 快捷鍵顯示的方法列表俗冻。

Pragma mark

這個(gè)通常用于一類方法的歸納

示例代碼：

#pragma mark - Life Cycle
- (void)viewDidLoad {
    [super viewDidLoad];
}

#pragma mark - Delegate
#pragma mark UITableViewDataSource
- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
    return 0;
}

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    return nil;
}

#pragma mark UITableViewDelegate
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
    
}

#pragma mark - Event Response

#pragma mark - Getters UI

效果如圖：

方法列表-01.png

可以看到，通過(guò) pragma mark 使用牍颈，可以讓方法分門(mén)別類迄薄，快速定位。

使用的注意點(diǎn):

• pragma mark 和 pragma mark - 都算是關(guān)鍵匹配對(duì)象煮岁，不可少打或改變大小寫(xiě)讥蔽，
• 對(duì)于pragma mark，mark后面只要不是字母画机，就都可以正常識(shí)別冶伞。
• 對(duì)于pragma mark - ，中劃線前后都一定有空格步氏，在代碼列表中响禽，會(huì)在其文字描述的上方顯示一個(gè)分割線

注釋標(biāo)簽

標(biāo)簽的功能類似于Pragma mark，會(huì)在類的方法列表中展示對(duì)應(yīng)的提示文案和特定icon，支持的有以下幾種注釋標(biāo)簽金抡。

• MARK: 文本內(nèi)容瀑焦，等同于#pragma mark
• TODO: 文本內(nèi)容，等待實(shí)現(xiàn)的功能
• FIXME: 文本內(nèi)容梗肝，需要修正的功能
• !!!: 文本內(nèi)容榛瓮，需要改進(jìn)的功能
• ???: 文本內(nèi)容，有疑問(wèn)的功能

代碼示例：

/**
 *  *** 打印一句話我要用好多代碼注釋標(biāo)簽 ***
 *  MARK:   等同于#pragma mark
 *  TODO:   等待實(shí)現(xiàn)的功能
 *  FIXME:  需要修正的功能
 *  !!!:    需要改進(jìn)的功能
 *  ???:    有疑問(wèn)的功能
 
 *  另外巫击，可以加上特定前綴方便檢索禀晓，效果依舊不變
 *  ET_TODO:   等待實(shí)現(xiàn)的功能
 */
NSLog(@"注釋標(biāo)簽");

效果如圖：

標(biāo)記注釋-01.png

說(shuō)明點(diǎn)：

• 五種提示都是關(guān)鍵字符串匹配，大小寫(xiě)和冒號(hào)都不能錯(cuò)
• 基于上面一點(diǎn)坝锰，可以自定義特定前綴粹懒，方便檢索（一堆TODO: !!!: 的項(xiàng)目還是很感人的）

這個(gè)可是說(shuō)是本人最喜歡的功能了，尤其是在代碼中要特別強(qiáng)調(diào)說(shuō)明一些事情時(shí)顷级。

warming

這個(gè)沒(méi)有什么過(guò)多說(shuō)的凫乖，其實(shí)在使用好各種標(biāo)簽后，完全沒(méi)有必要使用warming去產(chǎn)生一個(gè)讓人煩惱的黃色標(biāo)志弓颈。

示例代碼：

#warning 這里是代碼warming
#warning code warming

效果如圖：

warning-01.png

但是需要注意的一點(diǎn)是帽芽，warning對(duì)于中文支持是存在問(wèn)題的，我測(cè)試發(fā)現(xiàn)所有中文都不展示翔冀，且第一個(gè)單詞的首寫(xiě)字母一定會(huì)被大寫(xiě)展示导街。

attribute

__attribute__表示屬性，是Clang（GNU C）提供的一種源碼注釋纤子，
方便開(kāi)發(fā)者向編譯器表達(dá)訴求搬瑰，一般以__attribute__(*)的方式出現(xiàn)在代碼中。
為了方便使用控硼，一些常用屬性被定義成了宏泽论，經(jīng)常出現(xiàn)在系統(tǒng)頭文件中。
比如NS_CLASS_AVAILABLE_IOS(9_0) 就是 __attribute__(availability(9.0)) 
這個(gè)屬性的簡(jiǎn)單寫(xiě)法卡乾。
下面介紹一些可能會(huì)頻繁使用到的屬性

iOS-Foundation使用

attribute-iOSFoundation01.png

AFNetworking使用

attribute-AFN01.png

SDWebImage使用

attribute-SD01.png

對(duì)于中attribute函數(shù)屬性

• 函數(shù)屬性(Function Attribute)
  • noreturn
  • noinline
  • always_inline
  • pure
  • const
  • nothrow
  • sentinel
  • format
  • format_arg
  • no_instrument_function
  • section
  • constructor
  • destructor
  • used
  • unused
  • deprecated
  • weak
  • malloc
  • alias
  • warn_unused_result
  • nonnull
• 類型屬性(Type Attributes)
  • aligned
  • packed
  • transparent_union,
  • unused,
  • deprecated
  • may_alias
• 變量屬性(Variable Attribute)
  • aligned
  • packed
• Clang特有的
  • availability
  • overloadable

高級(jí)應(yīng)用-生成注解

ET_TODO:下期

注釋的使用

主要使用快捷鍵

• cmd + / 快速注釋選中行的代碼 （單行或者多行）
• command + Option + /翼悴，快速高級(jí)的邏輯注釋（常用于方法）
• option + 單擊 顯示注釋指示內(nèi)容
• 使用多行注釋一段邏輯 /* */，多行注釋不可嵌套多行注釋

代碼片段

Xcode的代碼片段(Code Snippets)可以用來(lái)自定義代碼塊说订，方便快速開(kāi)發(fā)

示例代碼：

@property (nonatomic,strong) <#Class#> *<#object#>; ///< <#note#>

關(guān)鍵寫(xiě)法： <#這里是默認(rèn)提示的文本#>

代碼片段-00.png

• 添加方式步驟1

代碼片段-01.png

步驟1圖中關(guān)鍵說(shuō)明

• 添加方式步驟2

代碼片段-02.png

• 添加方式步驟3(后續(xù)修改查看)

代碼片段-03.png

生成文檔

• docxygen http://www.stack.nl/~dimitri/doxygen/index.html

• headdoc http://developer.apple.com/opensource/tools/headerdoc.html

• appledoc http://gentlebytes.com/appledoc/

• docxygen

docxygen 感覺(jué)是這 3 個(gè)工具中支持語(yǔ)言最多的陶冷，可以配置的地方也比較多。我大概看了一下文檔毯辅，覺(jué)得還是比較復(fù)雜埂伦，而且默認(rèn)生成的風(fēng)格與蘋(píng)果的風(fēng)格不一致。就去看后面 2 個(gè)工具的介紹了思恐。另外沾谜，它雖然是開(kāi)源軟件膊毁，但是沒(méi)有將源碼放到 github 上讓我感覺(jué)這個(gè)工具的開(kāi)發(fā)活躍度是不是不夠。

• headerdoc

headerdoc 是 Xcode 自帶的文檔生成工具基跑。在安裝完 Xcode 后婚温，就可以用命令行：headdoc2html + 源文件名 來(lái)生成對(duì)應(yīng)的文檔。我個(gè)人試用了一下媳否，還是比較方便的栅螟，不過(guò) headerdoc 的注釋生成規(guī)則比較特別，只生成以 /*! */ 的格式的注釋篱竭。還有一個(gè)缺點(diǎn)是每個(gè)類文件對(duì)應(yīng)一個(gè)注釋文件力图，沒(méi)有匯總的文件，這點(diǎn)感覺(jué)有點(diǎn)不爽掺逼。

• appledoc

appledoc 是在 stackoverflow 上被大家推薦的一個(gè)注釋工具吃媒。有幾個(gè)原因造成我比較喜歡它：
它默認(rèn)生成的文檔風(fēng)格和蘋(píng)果的官方文檔是一致的，而 doxygen 需要另外配置吕喘。
appledoc 就是用 objective-c 生成的赘那，必要的時(shí)候調(diào)試和改動(dòng)也比較方便。
可以生成 docset兽泄，并且集成到 Xcode 中漓概。這一點(diǎn)是很贊的，相當(dāng)于在源碼中按住 option 再單擊就可以調(diào)出相應(yīng)方法的幫助病梢。
appledoc 源碼在 github 上胃珍，而 doxygen 在 svn 上。我個(gè)人比較偏激地認(rèn)為比較活躍的開(kāi)源項(xiàng)目都應(yīng)該在 github 上蜓陌。
相對(duì)于 headerdoc觅彰，它沒(méi)有特殊的注釋要求，可以用 /** */ 的格式钮热，也可以兼容 /*! */ 的格式的注釋填抬，并且生成的注釋有匯總頁(yè)面。

以下步驟主要參考該篇博客隧期， https://blog.csdn.net/xborong/article/details/85057696 </p>
appledoc-官方博客
appledoc-ibireme博客
appledoc-唐巧博客
的博客中的過(guò)程都有點(diǎn)問(wèn)題

appledoc version: 2.2.1 (build 1334)

工具安裝

git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh

腳本編寫(xiě)

#!/bin/bash
appledoc \
--output ./Doc \
-i *.m \
--project-name "IGUIKit" \
--project-company "Tencent" \
--no-create-docset \
--keep-undocumented-objects \
--keep-undocumented-members \
--no-warn-undocumented-object \
--no-warn-undocumented-member \
./IGUIKit

appledoc-腳本說(shuō)明.png

生成的文檔截圖樣式

appledoc-ET-01.png

appledoc-ET-10.png

appledoc-ET-11.png

appledoc-ET-12.png

結(jié)語(yǔ)

關(guān)于注釋飒责，兩年前自己就做過(guò)一次較為全面的了解，算是形成了自己的一套注釋風(fēng)格與規(guī)范仆潮，現(xiàn)在進(jìn)一步再總結(jié)宏蛉，過(guò)程中借鑒了Apple本身的注釋風(fēng)格，一些開(kāi)源框架的注釋風(fēng)格性置，以及一些網(wǎng)上的博客拾并，算是查缺補(bǔ)漏，也希望能夠幫助到各位。

注釋的寫(xiě)法那么多嗅义，最關(guān)鍵的目的還是要寫(xiě)屏歹，為了更好的閱讀代碼。至于你喜歡什么樣的注釋風(fēng)格之碗，自己喜歡的風(fēng)格或者與團(tuán)隊(duì)相近即可蝙眶。

如果有什么建議或問(wèn)題，歡迎溝通交流继控。

相關(guān)博客or文檔：

• 注釋規(guī)范
• 代碼結(jié)構(gòu)風(fēng)格
• iOS注解
• iOS快速代碼塊
• attribute說(shuō)明
• appledoc在Xcode10中的集成
  appledoc官方械馆、ibireme、唐巧 的博客中的過(guò)程都有點(diǎn)問(wèn)題
• appledoc-官方博客
• appledoc-ibireme博客
• appledoc-唐巧博客