ios开发注释规范

规范注释的好处：

1. 方便使用，会提示注释说明
2. 方便自己与他人阅读
3. 快速生成开发文档

好注释：

1. 可以使用快捷键[alt+点击]查看代码
2. 使用时可以智能提示注解(目前只有属性/方法的注释才会提示)
3. 类的层级分明(使用pragram)
   注：普通的注释(//和/**/)没有以上功能,只作为单纯的注释用

注释主要分4种：

1. 单行注释,有以下4种，满足前面提到的好注释的第1、2点
   /// 单行注释
   //! 单行注释
   /** 单行注释，此处其实可以多行 /
   /! 单行注释，此处其实可以多行*/
   如：

/// 这是name属性
@property (nonatomic, strong)NSString *name;

2. 行尾注释，有以下4种，满足前面提到的好注释的第1、2点
   ///< 行尾注释
   //!< 行尾注释
   /**< 行尾注释 /
   /!< 行尾注释 */

如：

/// 这是name属性
@property (nonatomic, strong)NSString *name; /**< 这是name属性 */

3、多行注释
xcode8以后可以使用快捷键[cmd + alt +/]，系统会根据方法的参数和返回值类型生成对应的多行注释
如

/**
 求两数之和

 @param firstNumber 第一个数
 @param secondNumber 第二个数
 @return 两数之和
 */
- (NSInteger)sumNumber:(NSInteger)firstNumber withNumber:(NSInteger)secondNumber;

4. 方法集注释

使用pragma
使用方式：

#pragma 什么都不显示
- (void)test1;

#pragma mark 显示文字，无分割线
- (void)test2;

#pragma mark - 显示分割线，并在分割线下方显示文字
- (void)test3;

可通过将注释格式保存为代码块的方式，提高注释的效率

其他注释:

1. 警告提示:#warning

xcode会在此处报一个黄色警告提示
如：#warning 产生黄色警告

2. 在注释中(什么注释都行)出现以下字样，会有特别的作用

MARK: 等同于#pragma mark
TODO: 等待实现的功能
FIXME: 需要修正的功能
!!!: 需要改进的功能
???:有疑问的功能
Comments containing: (注：未知此字样的具体用法)
注:以上字样可以放进//、///、//<、//、//、/</等注释方式中

// MARK: - 方法集
// TODO: 等待实现
// FIXME: 有bug，需要修改
// !!!: 逻辑混乱，需要完善
// ???: 具体干什么用的？
- (NSInteger)sumNumber:(NSInteger)firstNumber withNumber:(NSInteger)secondNumber;

注释中常用的标签：
@brief : 使用它来写一段你正在文档化的method, PRoperty, class, file, struct, 或enum的短描述信息。
@discusstion: 用它来写一段详尽的描述。如果需要你可以添加换行。
@param:通过它你可以描述一个 method 或 function的参数信息。你可以使用多个这种标签。
@return: 用它来制定一个 method 或 function的返回值。
@note:注意点,补充说明
@see: 用它来指明其他相关的 method 或 function。你可以使用多个这种标签。
@sa:同上
@code ： 使用这个标签，你可以在文档当中嵌入代码段。当在Help Inspector当中查看文档时，代码通过在一个特别的盒子中用一种不同的字体来展示。始终记住在写的代码结尾处使用@endcode标签。
@remark : 在写文档时，用它来强调任何关于代码的特殊之处。

记录文件常用标签：
@file: 使用这个标签来指出你正在记录一个文件（header 文件或不是）。如果你将使用Doxygen来输出文档，那么你最好在这个标签后面紧接着写上文件名字。它是一个top level 标签。
@header: 跟上面的类似，但是是在 HeaderDoc中使用。当你不使用 Doxygen时，不要使用上面的标签。
@author：用它来写下这个文件的创建者信息
@copyright: 添加版权信息
@version: 用它来写下这个文件的当前版本。如果在工程生命周期中版本信息有影响时这会很重要。
@class: 用它来指定一个class的注释文档块的开头。它是一个top level标签，在它后面应该给出class名字。
@interface: 同上
@protocol: 同上两个一样，只是针对protocols
@superclass: 当前class的superclass
@classdesign: 用这个标签来指出你为当前class使用的任何特殊设计模式（例如，你可以提到这个class是不是单例模式或者类似其它的模式）。
@coclass: 与当前class合作的另外一个class的名字。
@helps: 当前class帮助的class的名字。
@helper: 帮助当前class的class名字。

参考：https://blog.csdn.net/zeng_zhiming/article/details/68925543