java注释

Java提供三种注释方式: 单行注释、多行注释、文档注释.

# javadoc 注释标签语法

标签	作用域	说明
@author	类	标明开发该类模块作者
@version	类	标明该类模块的版本
@see	类, 属性, 方法	参考转向(相关主题)
@param	方法	对方法中某参数的说明
@return	方法	对方法返回值的说明
@exception	方法	抛出的异常类型
@throws	方法	与@exception相同
@deprecated	方法	不建议使用该方法

注释原则

下面是我自己看到和用过的注释原则:

1. 注释准确简洁 
   内容简单明了、含义准确, 尽量用最少的语言把问题阐述清楚, 防止注释的多义性,错误的注释不但无益反而有害.
2. 避免复杂注释 
   如果需要用复杂的注释来解释代码, 请检查此代码是否应该重写. 尽一切可能不注释难以理解的代码, 最好选择重构.
3. TODO List 
   为尚未完成的代码添加TODO注释, 提醒自己还需后续完善.
4. 注释形式统一 
   在整个项目中,使用一致的结构样式来构造注释.
5. 注释与代码同步更新 
   边写代码边注释,因为以后很可能没有时间来写注释了(可能在今天看来很明显的东西六周以后或许就不明显了). 通常描述性注释先于代码创建、解释性注释在开发过程中创建、提示性注释在代码完成之后创建. 修改代码的同时修改注释,保证代码与注释同步.
6. 注释就近 
   保证注释与其描述的代码相邻, 在代码上方或右方(最好上方)进行注释.
7. 注释不要过多 
   注释必不可少,但也不应过多,注释占程序代码的比例少于20%为宜.注释是对代码的“提示”,而不是文档. 如果代码本来就一目了然就不加注释.
8. 删除无用注释 
   在代码交付或部署发布之前, 删除临时或无关注释, 避免日后维护中产生混乱.
9. 必加注释之处 
   
   • 典型算法必有注释
   • 代码不明晰处必有注释
   • 在循环/逻辑分支组成的代码中加注释
   • 为他人提供的接口必有注释
   • 在代码修改处加修改标识