为什么要写注释？

给别人看

给自己看

java 文档注释?

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

怎么能写好注释?

什么情况需要

  • 典型算法必有注释

  • 代码不明晰处必有注释

  • 在循环/逻辑分支组成的代码中加注释

  • 为他人提供的接口必有注释

  • 在代码修改处加修改标识

如何生成注释

java doc 插件

手写

拓展阅读

swagger-ui 基于注解的 java 文档生成。

自己设计一套注释生成插件

idoc

参考资料

https://yq.aliyun.com/articles/455242