注释

1.文件注释

在implementation file头部按照如下格式进行说明：

//
//  HoriLockView.m
//  HoriSmartCommunity
//
//  Created by chenjiangchuan on 2017/10/29.
//  Copyright © 2017年 chenjiangchuan. All rights reserved.
//
//  Description: 文件描述
//  History:
//    1. YYYY/HH/DD [Author]: update log;
//

可以通过修改___FILEBASENAME___.m文件自动生成上面的注释，路径：/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/File\ Templates/Source/Cocoa\ Touch\ Class.xctemplate

Xcode8：

//
//  ___FILENAME___
//  ___PROJECTNAME___
//
//  Created by ___FULLUSERNAME___ on ___DATE___.
//___COPYRIGHT___
//
//  Description: 文件描述
//  History:
//    1. YYYY/HH/DD [Author]: update log;
//

Xcode 9修改方式如下，详细请查看 Xcode 9 新功能之自定义文件模板

新增文件 ~/Library/Developer/Xcode/UserData/IDETemplateMacros.plist，内容如下：

{
    FILEHEADER = "\n//  ___FILENAME___\n//  ___PROJECTNAME___\n//\n//  Created by ___FULLUSERNAME___ on ___DATE___.\n//  ___COPYRIGHT___\n//\n//  Description: <#文件描述#>\n//  History:\n//    1. ___DATE___ [___FULLUSERNAME___]: 创建文件;\n//";
}

2.方法注释

理论上好的代码应该是self-documenting，但统一规范，需要详细的注释，定义在Header file中的方法一定要有详细注释：

例子：

/**
 *  @author chenjiangchuan, 2017-06-20 14:06
 *
 *  更新sip参数
 *
 *  @param number     专用号码
 *  @param domain     sip域
 *  @param proxy      代理
 *  @param port       代理端口
 *  @param backupPort 备用代理端口
 *  @param password   sip密码
 */
+ (void)updateSipConfigWithNumber:(NSString *)number
                           domain:(NSString *)domain
                            proxy:(NSString *)proxy
                             port:(int)port
                       backupPort:(int)backupPort
                         password:(NSString *)password;

/**
 *  @author chenjiangchuan, 2017-06-15 15:06
 *
 *  注册sip
 *
 *  @param uuid 设备的UUID
 *
 *  @return YES：成功
 */
+ (BOOL)registerSipWithUUID:(NSString *)uuid;

• 首先是作者加上创建该方法的时间；
• 方法的描述；
• 参数；
• 如果有返回值，需要对返回值进行描述。

3.属性注释

属性注释统一采用 /** */

/** 存放已绑定的小区 */
@property (copy, nonatomic) NSArray <HoriAreaRecord *> *areaArray;

4.其他注释

比如方法内部的注释使用//，如果注释中引用了参数名或者方法名，使用||将参数或者方法括起来：

/**
 *  @author chenjiangchuan, 2017-06-15 15:06
 *
 *  注册sip
 *
 *  @param uuid 设备的UUID
 *
 *  @return YES：成功
 */
+ (BOOL)registerSipWithUUID:(NSString *)uuid {
    // |uuid|为iPhone设备的识别码
    reigsterSip(uuid);
}