新手在开始参与一个开发项目的时候，会把大部分的时间耗费在阅读项目的需求文档、开发文档和代码，一篇好的需求文档和开发文档会帮助新手很快的理解项目的目标和进度，而新手对于代码的阅读会先从代码的注释开始。拥有良好注释的代码可以省去团队其他的开发者好多时间，不至于让其他参与者去一行一行的阅读代码，去不断地加断点查看代码地跳转逻辑，接下来我们就谈谈iOS开发中使用的一些注释。

#pragma mark

确切地说，这是Xcode编译器特定得编译命令，它的作用就是在代码地编辑器中，将顶部的方法函数弹出菜单按层次分开，方便于我们的查找。一般的使用方法是在想要分层的第一个方法或函数上面加上#pragma mark -　和#pragma　mark something(你的分层定义)。此外其他常用到的，是在我们想要标识代码的地方加上#warning，这样运行时编译器会自动帮助我们将代码标识到issue　navigator。

自定义标示

使用自定义的特殊标识符，例如//TODO:或者是//FIXME:。使用这一类的特殊标识符，首先需要在Xcode中添加支持，在我们的Target中，选择Build Phases，Xcode 6将Build Phases从Build Settings分离了出来。在Build Phases选择New Run Script Phase，然后输入：

1
2

KEYWORDS="TODO:|FIXME:"
find "${SRCROOT}"  ?name"?.h"?or?name"?."        -print0 | xargs -0 egrep --with-filename --line-number --only-matching "($KEYWORDS).*$" | perl -p -e "s/($KEYWORDS)/ warning: $1/"

代码注释

上面的俩种可以算是编译器识别的命令，下面我们来说一下传统意义上的代码注释。不管在使用哪种语言，我们一般都会使用到代码注释，而不同的语言有不同的注释规范，例如一般的单行注释，我们会使用“//”，而多行注释则会使用"/*......*/"，而对于iOS开发者来说，代码注释也拥有属于它自己的一套规范。下面就是一些常用的iOS的代码注释，这些衍生的注释目的是方便文档生成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

   

/// Single line comment spreading （多行文本）
     /// over multiple lines.
/** Single line comment. */ （单行文本）
/** Single line comment spreading （多行文本）
 * over multiple lines.
 */
/** Single line comment spreading （多行文本）
 over multiple lines. No star.
 */
/*! Single line comment. */ （单行文本）
/*! Single line comment spreading （多行文本）
 over multiple lines.
 */

方法注释

在iOS开发代码中有一种对方法的注释 ，其中包含了特有的指令：

1
2
3
4
5
6
7
8
9

/**
 * @brief 带字符串参数的方法.（具体描述）
 * @param value 值.（参数描述）
 * @return 返回value.（返回值描述）
 * @exception NSException 可能抛出的异常.（抛出异常描述）
 * @see someMethod （关联描述）
 * @warning 警告: appledoc中显示为蓝色背景, Doxygen中显示为红色竖条.（警告描述）
 * @bug 缺陷: appledoc中显示为黄色背景, Doxygen中显示为绿色竖条.（缺陷描述）
 */

生成开发文档

说起上面的这种iOS开发中的代码注释，就不得不说一下iOS开发中的文档生成，一个良好的代码文档可以帮助其他开发者很好的了解代码结构和具体内容。而时下比较流行的几个文档生成工具有下面几种，关于iOS代码文档的具体生成，我推荐朋友们观看这篇 唐巧的技术博客——-使用Objective-C的文档生成工具。

1. 第三方工具Doxygen
2. Xcode自带的HeaderDoc
3. 默认与苹果官方文档风格类似的AppleDoc

原文:大专栏  使用注释提高iOS开发效率