关于添加注释的正确姿势

关于添加注释的正确姿势

最近在看到一篇关于开发规范的文章,的确,作为初级程序员连最基本的代码规范一直都没有达标,在此特意班门弄斧记录下来以后的代码规范以此文章作为标准.

1. 【强制】所有类都必须添加创建者和日期。
2. 【强制】所有的枚举类型字段都必须有注释，说明每个数据项的用途。
3. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等修改。
4. 【参考】特殊标记，请注明标记人与标记时间。

如何在idea中设置在创建类时就自动添加创建者和日期?
如下图,其实你只需要找到settings–>file and code templates添加一个文件file header

代码如下.

/**
 * @author  hw
 * @date  ${DATE} ${TIME}
 * @version 1.0
 */

当你创建类后,自动将会添加作者,日期以及版本.

常见的注释以及写法

1. 常规注释
   常规注释主要指普通的注释，比如每个接口几乎都会有的：接口的功能，接口的参数以及含义，接口异常和出现异常的原因，接口的返回值。
2. 工具函数注释
   工具类的注释主要包含：函数的功能，函数的使用范例，函数的参数和返回值描述，该函数出现的起始版本等。
3. 废弃代码的注释
   废弃的接口要给出废弃的原因和替代方案等。
4. 特殊注释
   TODO 注释主要用在本该做还没做的事项。
   例如格式:包含功能名称、责任人、事项、添加时间和预处理时间等信息。

注意规定

1. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。方法内部多行注释
   使用 / / 注释，注意与代码对齐。
2. 【强制】 所有的类都必须添加创建者和创建时间。
3. 【强制】如果代码逻辑和注释不符，必须进行修改。
4. 【推荐】方法注释中建议添加相关需求文档，接口文档地址。
   例如:

/**
 *  xxx功能（功能描述）
 *
 *  需求文档：{@link <a href="http://doc.imooc.com/xxx/process/0001"/>}
 *  接口文档：{@link <a href="http://api.imooc.com/xxx/process/0001"/>}
 *  对接人员：@张三
 *
 * @param param  参数描述
 * @return  返回值描述
 */
public Object something(Object param){
    // 1. 查询xx数据
    
    // 2. 过滤yy条件
    
    // 3. 组装结果
}

5. 【推荐】容易费解的地方一定要加注释。
6. 【推荐】推荐 git 提交注释的格式为： [功能名称] < 提交类型 > 修改点描述。
   例如:

[a功能] <add>  某某接口

[a功能] <delete> 删除了无用的注释

[a功能] <update>  修改函数命名

[a功能] <fix> 修复了某个错误

总结

注释的目的是让读者更快理解代码的含义。