写代码注释是十分重要的一件事。如果你的代码维护或迭代的代价很大，那对接手你代码的人可能会十分痛苦。好的注释能够一定程度上解决这一问题，这也是一个码农的基本素养。但是，注释并不是越多越好。好的代码应该是能够自我解释的。Objective-C 语法中的方法名本身就对其中的参数进行了解释，所以在写注释之前最好先检查下自己命名的问题，想想这些注释是不是有必要的。对一些简单的变量、方法和逻辑，是不需要注释的，这种注释只会分调用者的注意力。注释应该只在如下场景中出现。
- 解释实现文件中复杂的逻辑
- 对代码进行标注
- 对接口进行说明
解释实现文件中复杂的逻辑
在实现文件中，有时候会有一些复杂的逻辑，这种情况通过看代码去理解代价往往很大。如果不写备注，可能以后连自己都很难维护。所以，就算现在你对这些代码的逻辑有很清晰的理解，也最好写上备注，因为以后你肯定会忘记。这种注释由于不需要文档化，也不需要联想，所以使用 C/C++ 的注释风格就可以。当然如果你有文档化的需求，那还是按照统一的注释风格。
// 这是注释
/* 这是也是注释 */
对代码进行标注
在程序中，我们见过最多的注释莫过于//TODO了。这种注释如果在后边加上“:”就能在方法列表中显示，效果类似于#pragma mark。Xcode支持类似功能的注释有如下几种。
//MARK:MARK
//TODO:TODO
//FIXME:FIXME
// !!!:!!!
//???:???
这样的注释能够起到对代码进行标记的作用。比如项目中如果存在还没有完成的功能就可以加上//TODO:Response button event。如果某块代码需要修改，可以加上//FIXME:There is a problem on iOS7。如果你需要警告他人// !!!:DO NOT TOUCH MY CODE!。或者你对哪里的代码有不解（不满）//???:What is this shit。如果你想在方法内部实现像#pragma mark一样的标注，就可以使用//MARK:Initialization，是的，就是这么简单。如果你很另类，你还可以这样来注释代码。
对接口进行说明
当我们封装库或在开发较复杂的项目时，因为接口需要供多人使用，所以对接口的注释说明就十分重要。
从注释生成文档
复杂的接口注释有时候生成文档会更方便查看。对于程序设计的文档，业界的标准做法都是自动生成。一般我们会将文档嵌入地以某种规范的格式以注释的形式写在实际代码的上方，这样文档的自动生成器就可以扫描源代码并读取这些符合格式的注释，最后生成漂亮的文档了。Java语言本身就自带 JavaDoc 命令，可以从源码的注释中抽取文档。对于 Objective-C 来说，这方面的自动生成工具有 Apple 标准的 HeaderDoc，以及第三方的 AppleDoc 或者 Doxygen 等。它们分别的官方网址如下。
Docxygen 支持的语言最多，可以配置的地方也比较多。但是默认生成的风格与苹果的风格不统一。HeaderDoc 是 Xcode 自带的文档生成工具。在安装完 Xcode 后，就可以用命令行headerdoc2html + 源文件名来生成对应的文档。不过 HeaderDoc 的注释生成规则比较特别，只生成以/*! */的格式的注释。还有一个缺点是每个类文件对应一个注释文件，没有汇总的文件。而 AppleDoc 是在 StackOverflow 上最被大家推荐的。它默认生成的文档风格和苹果的官方文档一致。它还可以生成 docset 并集成到 Xcode 中。这样在源码中使用 Alt + 双击 就可以进入文档查看了。相对于 HeaderDoc，它没有特殊的注释要求，可以用/** */的格式，也可以兼容/*! */的格式的注释，并且生成的注释有汇总页面。
注释通用格式
从 Xcode5 开始，IDE 默认集成了提取文档注释并显示为 Quick Help 的功能，从那以后，能被 Xcode 识别的文档注释就成为了事实上的行业标准。当我们按照Xcode支持的规则写注释的时候，就可以通过Alt + 单击的方式唤起 Quick Help。而且在 Xcode 自动联想时也能看到对应的注释。如果使用 AppleDoc 生成并集成了文档，还可以Alt + 双击进入说明文档。由于 Xcode Quick Help，Docxygen，HeaderDoc 和 AppleDoc 都有自己的规则。下边就简单介绍一些常用的且兼容性强的规则。更详细的说明可以分别访问他们的官方网站或者本篇的参考文献。
首先，由于 HeaderDoc 只支持这样/*! */一种格式的的注释，所以如果你想用 HeaderDoc，就可以跳过下边这一段了。
先说行尾注释。生成文档的话，只有Docxygen是支持行尾注释的。但是所幸 Xcode Quick Help 的支持让我们有了使用的理由。
/**< 行尾注释1. AppleDoc 不支持会变为下一项的注释, Quick Help 支持，Doxygen 支持, 根据英文句号自动切分简要描述与详细描述. */
/*!< 行尾注释2. AppleDoc 不支持会变为下一项的注释, Quick Help 支持，Doxygen 支持, 会全部当作详细描述, 而缺少简要描述. */
///< 行尾注释3. AppleDoc 不支持会变为下一项的注释, Quick Help 不支持, Doxygen 支持。
//!< 行尾注释4. AppleDoc 不支持会会忽略, Quick Help 支持, Doxygen 支持。
为了避免 AppleDoc 误将行尾注释当作下一项的注释，故推荐第4种注释//!<。行首的单行注释除了 HeaderDoc 外，其他都是支持///的。但是，你如果使用了这样格式的行首单行注释，那用 HeaderDoc 生成文档时就会报错Skipping. No HeaderDoc comments found.。行首的多行注释除了 HeaderDoc 外，其他也都是支持/** */这样格式的。同样，这样的注释 HeaderDoc 也无法生成文档。综上，如果你想要使用 HeaderDoc ，就老老实实都用/*! */写在行首。如果你放弃了 HeaderDoc ，那你就可以使用如下更通用的注释方式。如果你使用的是AppleDoc， 则要避免使用行尾注释。
- 行首单行注释
/// - 行尾单行注释
//!< - 行首多行注释
/** */
通用二级标签
多行注释中是支持二级标签的。Xcode 基本支持所有的二级标签颜色加深的功能。二级标签可以在生成文档、联想和使用 Quick Help 时显示。不加任何标签的情况的下生成文档，单行注释默认为简要描述。多行注释默认为详细描述。在使用多行注释的时候也可以在不加标签的情况下同时生成简要描述和详细描述。使用单行注释时，只有 Doxygen 会根据英文句号自动切分简要描述与详细描述。
/** 简要描述
* 详细描述
*/
///简要描述.详细描述
多行注释中的简要描述也可以用@brief来代替。除此之外还有很多支持的二级标签。这里列举一些 AppleDoc 和 Doxygen 均支持的常用二级标签。
/**
* @brief <title>: 简要注释. appledoc中仅对属性、方法有效，对类、协议 无效，会造成后续内容解析失败.
* @param <name> <description>: 参数描述.
* @return <description>: 返回值描述.
* @exception <name> <description>: 异常描述.
* @see <name>: 参见.
* @sa <name>: 参见. 同@see.
* @warning <text>: 警告.
* @bug <text>: 警告.
* @name <title>: 组名. 用于给成员们分组, 既文档中Tasks区的子类别.
* 代码块 `int sum = 0;`
* 多行代码块:
* int sum = 0;
* for(int i = 1; i <= 10; i++) {
* sum += i;
* }
* 无序列表:
* - first
* - second
* - third
* 有序列表:
* 1. first
* 2. second
* 3. third
* 多级列表:
* - abc
* - a
* - b
* - c
* - rgb
* - red
* 1. first.
* 1. alpha.
* 2. beta.
* 2. second.
* 3. third.
* - green
* - blue
* 链接:
* <http://www.xuyafei.cn>
* [xuyafei](<http://www.xuyafei.cn>)
*/
下边是 Quick Help 支持的常用二级标签。
/**
* @brief It converts temperature degrees from Celsius to Fahrenheit scale.
* @param fromCelcius The celsius degrees value.
* @return float The degrees in the Fahrenheit scale.
* @code
* float f = [self toCelsius:80];
* @endcode
* @remark This is a super-easy method.
*/
note_quick_help.png
* appledoc的安装与使用
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
appledoc -o 导出目录 -p "项目名称" -c "公司名称" .
微博：weibo.com/xuyafei86
Github：github.com/xiaofei86
网友评论