iOS常见注释规范

一、几种不同的注释方式

注释的作用这里就不用赘述了，在项目中，不建议到处写注释，好的代码应该是用代码就可以说话的，比如见名就知意的变量名、属性名、方法名，比如把做某一项任务的功能单独放一块等。在这里总结一些自己项目中常用的注释。首先我把自己已知的注释方式分为下面几种：
1，单行注释（双杠注释）：双斜杠//，格式：// 注释内容。
2，三杠注释：///，格式：/// 注释内容。
3，多行注释：/**/，格式：/* 注释内容 */。
4，多行注释扩展版本：/**< 注释内容 */、/**> 注释内容 */

二、注释的使用

单行注释在一个文档的任何位置都可以添加，多行注释主要用于对文档介绍和方法的具体描述。当然多行注释也常用于实例变量、属性、方法前注释，主要目的是为了开发维护和在调用的地方能够快速查看这个实例变量、属性、方法的注释描述。三杠注释跟多行注释作用一样。下面列举三杠注释和多行注释的常见使用场景。
1， 实例变量、属性、枚举注释
/// 注释内容和/* 注释内容 */放在实例变量、属性、方法的前一行，/**< 注释内容 */放在实例变量、属性、方法的同一行，在调用的地方查看实例变量、属性、方法的注释时结果是一样的。/**> 注释内容 */表示注释当前行的下一行内容。
之所以列举出三种，是为了让我们根据实际应用场合有不同的选择。比如在枚举注释和实例变量前建议使用/**< 注释内容 */方式。

2，方法注释
Xcode 8.0 之前，快速给方法添加注释我们一般用VVDocument插件，只需连按三个///即可快速添加注释。Xcode 8.0 之后， Xcode内置了快速添加注释的功能，只需按Command + Option + /。

3，方法集注释
#pragma mark - 注释内容(查看时带分割线)
#pragma mark 注释内容(查看时不带分割线)

下面附上我定义的Person类源码：

#import <Foundation/Foundation.h>

/*
 * 性别
 */
typedef enum : NSUInteger {
    GenderTypeUnknown = 0,   /**< 未知*/
    GenderTypeMan = 1,       /**< 男*/
    GenderTypeWoman = 2,     /**< 女*/
} GenderType;

@interface Person : NSObject
{
    /// 手机号1
    NSInteger _phoneNum1;
    /** 手机号2 */
    NSInteger _phoneNum2;
    NSInteger _phoneNum3; /**< 手机号3 */
    
    NSInteger _phoneNum4; /**> 手机号5 */
    NSInteger _phoneNum5;
}

#pragma mark - 属性
/// 姓名
@property (nonatomic, copy) NSString *name;
/** 年龄 */
@property (nonatomic, assign) NSInteger age;
@property (nonatomic, assign) GenderType gender; /**< 性别 */

#pragma mark - 实例化对象方法
/**
 实例化一个对象

 @param name 性别
 @param age 年龄
 @param gender 性别
 @return 返回一个对象
 */
- (instancetype)initWitName:(NSString *)name age:(NSInteger)age gender:(GenderType)gender;

@end

三、快速添加注释

上面介绍了要给方法快速添加注释，Xcode 8.0 之前可以安装VVDocument插件，Xcode 8.0 之后可以按Command + Option + /。其实给实例变量、属性、方法添加快速注释也是一样，只不过给实例变量、属性、方法添加的注释可能不是我们想要的效果。所以要实现快速添加/* 注释内容 */和/**< 注释内容 */格式的注释，我们可以自己写代码片段的方式来快速添加。

以上是我总结的项目中注释的常见使用，有什么需要添加和修改的地方，欢迎小伙伴在下面给我评论或者发私信。小伙伴也可以关注我的微博，我会不定期转发分享一些比较好玩热门的技术和第三方库。