Java类头部注释应使用Javadoc还是多行注释?
Java类头部注释:选Javadoc还是多行注释?
嘿,这个问题问得很接地气!对于Java类的头部注释,我强烈推荐用Javadoc的/**格式,而非普通的多行/*注释,原因如下:
- 官方标准,支持自动文档生成:Javadoc是Java官方指定的文档注释规范,你可以通过
javadoc命令直接把这些注释转换成结构化的HTML文档。不管是团队协作还是后续维护,其他人通过生成的文档就能快速get到类的核心信息,这可是普通多行注释做不到的。 - 支持标准化标签,信息更规范:Javadoc自带一系列专用标签,比如
@author、@since、@version等,能把作者、创建时间、版本这类信息标准化。比起你手动写Name:、Date:,用标签的方式不仅更专业,还能避免格式混乱。比如规范的写法可以是:
/** * 示例类,用于演示Javadoc的规范用法 * @author Raymo111 * @since 2018-04-04 * @description Stack overflow question about headers */ public class whatever { //Some code here }
- IDE友好,提升开发效率:现在主流的Java IDE(比如IntelliJ IDEA、Eclipse)都对Javadoc有深度支持——输入
/**再回车,就能自动生成注释模板;写代码时还能实时弹出注释提示,省心又高效。
至于普通的/*多行注释,它更适合用来临时注释掉代码块,或者写一些不需要纳入官方文档的内部备注,放在类头部就有点用错场景啦。
内容的提问来源于stack exchange,提问作者Raymo111




