Skip to content

Latest commit

 

History

History
52 lines (31 loc) · 1.94 KB

Java_comment.md

File metadata and controls

52 lines (31 loc) · 1.94 KB

Java 注释

在类上打@author注释，多个作者时打多个

虽然 Git 或 Svn 能精确 blame，但是在没必要精确的工具中方便直接读@author判断作者

使用文档注释，文档注释中使用HTML格式化，使用链接便于快速跳转查看

例如换行应该使用
，这里br不加/是因为JDK源码里绝大多数不加/,列条目用

  • 等

    行末注释改文档注释正则替换(支持带多个注解)

    (?>![/\w)])((?:\n[ \t]*@.+)*)(\n[ \t]*)(.*)\s*//\s*(.++)

    $2/** $4 */$1$2$3$4

    使用{@link package.class＃member label}便于在相关程序中快速跳转

    测试案例链接到测试类应使用@see，不加package，因为在同一个包里，使链接保持简短

    /**
 * @see IncludeTest
 */
public class IncludeTest {}

    不要在开发工具(IDE)中设置自动注释格式，只需做必要的注释。

    设置自动注释格式而没有对应的内容时会在代码中留下很多无用的内容， 而且不存在的标签在IntelliJ IDEA中默认会报红提示。 好的代码在参数、返回字段等地方应该是不言自明的， 但是类似返回的值为空是哪些情况等需要说明的地方还是需要手动注释。

    使用// FIXME 测试挡板标注临时代码

    • 原则上不应编写临时挡板
    • 如果是单次的可以用远程调试下编辑编译的方式单次热替换
    • 常规挡板应使用数据库或配置文件判断去实现（如 spring 和 maven的 profile）

    因为在某些项目中IDE生成的代码带有TODO标签，所以用FIXME，并且用中文让审核代码的同事也能一眼关注到

    带逻辑的get/set方法加注释，IDEA 等工具不能自动获取字段注释

    弃用的时候在文档注释上加@deprecated说明应如何更新，可以加上原因

    翻译性开发时适当添加原字段和方法的名称注释，便于对照维护，到了适当时期再删除

    •