Java 文档注释规范

关键字：怎么写文档注释、文档注释语法、文档注释规则

谦虚的高逼格搬砖人
全部原创，从零开始
你可以不喜欢，但是不能骂人
你可以指点，但是不能装逼，因为我是有骨气的干饭人

初来乍到，不秀一下自己的能耐怎么能让大伙服你？

怎么才能让大伙眼前一亮，是骚气的代码吗？

不好意思，骚气的代码已经是后话了，高逼格的代码往往是毫不经意的锋芒，从你的文档注释开始，你就是他心目中的玛格丽特，他毫不犹豫的想邀请你与他共舞！

一、文档注释介绍

1.1 为什么要写文档注释

很多人觉得写代码不去写注释才是大师的标配，让那些楞逼看着你神一样的代码，呆若无神，比半夜起来上厕所的眼睛还空洞，你才能安心的蹲在厕所的坑上狂喜。其实大错特错，你已经跌落了神坛，看你代码的人估计把你骂了很多遍。

讲真，没有注释的代码是没有灵魂的，像直男开房后的无所事事，像学校食堂里西红柿炒鸡蛋中西红柿的寂寞！

这样的代码极不利于传承，不仅加重了阅读者的学习成本，还为猝死的路上添砖加瓦

毫不夸张的说自从我的代码写了骚气的文档注释后，大伙花在看文档注释的时间比看我的代码的时间更多，隔壁的Jack拍着我的肩膀直呼：“TMD，你这个文档注释骚气的我受不了了”

毕竟在当代社会，大家金玉其表，给代码的镶金添玉也会变成了文档注释，谁会愿意花那么多时间从你骚气的代码中研究你到底有多内涵！

贴一段鄙人粗俗但是很有气质的代码

1.2 文档注释是个什么玩意

言归正传，作者学习和使用的文档注释，全部借鉴于Spring的源码，同时将这些文档注释做了收集和整理

文档注释中使用了很多标签，每个标签都有不同的作用，我会将我吐血的整理和每天夜晚身体的精华整理出来分享给各位，同时标注出每个文档注释在源码中的出处！

• 文档注释的构成
  ① 第一部分：代码的简要介绍
  ② 第二部分：代码的功能详细描述
  ③ 第三部分：代码中重要方法的引用
  该文档注释引用自 org.springframework.context.annotation.Configuration.value()
  

• 文档注释中主要的元素
  ① 标签，例如：<em></em>
  ② 引用，例如：{@link AnnotationConfigApplicationContext}

• 写好文档注释的要求
  ① 知道每个标签的作用
  ② 言简意赅，不是写的越多越好，能少两个字绝不多写三个字

二、文档注释怎么写

2.1 常用的标签及介绍

• 详细描述标签 <p>
  ① 标签说明：一般使用在文档注释的第二部分，用于详细的说明
  ② 使用潜规则：这是个裸吊，没有女朋友，它没有闭标签，是个烂透了的单身狗，但是很高贵
  ③ 两种写法：分别作用在类上和方法上是不同的。
  在类上的时候需要空行，在方法上不需要空行，看下面的两个示例：
  该文档注释引用于：org.springframework.context.annotation.Scope

该文档注释引用于：org.springframework.context.annotation.Scope.proxyMode()
  
• 代码示例标签 <pre></pre>
  ① 便签说明：你没看错，文档注释里还可以写代码示例的
  ② 使用潜规则：使用有风险，不是很牛逼的代码，不建议用这个便签在文档注释里写代码示例，剑气可能会伤到架构师
  ③ 写法注意：用到的特殊符号要写转译
  该文档注释引用于：org.springframework.context.annotation.Bean
  
• 强调及引用标签：<em></em>
  ① 标签说明：除强调之外，当引入新的术语或在引用特定类型的术语或概念时作为固定样式的时候也使用该标签
  ② 使用潜规则：使用的频率高，使用范围很广
  ③ 写法注意：想清楚什么是术语，什么是强调，当我们写了个方法，需要情调这TM的就是个砍柴的方法，你个楞逼就要用它造一个女朋友，不好意思出了事故别怪我，因为我用了<em>标签进行了说明
  <em>标签的作用为术语引用，该文档注释引用于 org.springframework.context.annotation.Bean

<em>标签的作用为强调，该文档注释引用于 org.springframework.context.annotation.Bean
  
• 多标题介绍标签：<h3>
  ① 便签说明：你写了个类，这个类实在是太强了，两三句话的描述根本不够写，那你用它就对了
  ② 使用潜规则：有很多段描述，每段来这么一个标签，标题的作用，每段的描述有个标题
  ③ 写法注意：你竟然用了这个标签，你已经是架构师了，大哥，收了我吧
  该文档注释引用于 org.springframework.context.annotation.Bean
  

2.2 强调及很重要的写法

你写的代码总一定有很多需要特别的温馨提示，一定得告诉用你代码的人，不然你离了职都不安心啊，那就是以下这些，让后来的砖头感谢你把！

• <b> 标签 + NOTE：提示
  该文档注释引用于 org.springframework.context.annotation.CommonAnnotationBeanPostProcessor
  
• <strong> 标签
  该文档注释引用于 org.springframework.boot.autoconfigure.condition.ConditionalOnProperty
  
• 直接使用note提示
  该文档注释引用于 org.springframework.context.annotation.Bean.destroyMethod()
  

2.3 变量、方法、类的引用的写法

• 引用说明
  ① 引用某个方法、某个变量、某个变量名
  ② 用在文档注释的第二部分和第三部分
  ③ 两种写法：第二部分用这个{}，第三部分用这个@see

• @see 的使用
  ① 使用在文档注释的第三部分
  ② 为什么要用：特别希望用你方法的这个人去看下这两处的引用，不然你个菜鸡 TM 看不懂，还骂我写的烂，好好体会代码的精妙
  ③ 注意区分当前类的引用和外部类的引用
  该文档注释引用于 org.springframework.context.annotation.Bean.destroyMethod()

该文档注释引用于 org.springframework.context.annotation.Bean.name()
  

• {@link org.springframework.core.annotation.Order @Order} 应用其他类的方法
  ① 使用在文档注释的第二部分
  ② 为什么要用：告诉你引用的这个要做什么，而不是瞎写的
  ③ 注意：如果是引用当前类的变量和方法，直接这么写{@link #name}
该文档注释引用于 org.springframework.context.annotation.Bean
  

• {@code } 引用一些代码，没办法写成上面那种的
  ① 有些代码，我们没办法写成上面那种，但是逼格不能丢，那就用这种
  ② 多看看源码中的注释，我的总结你可能看不懂，不怪我啊，只能这么描述了
  该文档注释引用于 org.springframework.context.annotation.Bean
  

2.4 常见的缩写

• e.g. ：举例
  引用自 org.springframework.boot.SpringBootConfiguration
  
• a.k.a. :又名，别名
  引用自 org.springframework.boot.SpringBootConfiguration

三、总结

① 看了很多源码里的文档注释，每个人都有每个人的写法，没有什么硬性的规则，但是写的漂亮的还是很多的，要有自己的风格，同时得让大家能接受很重要
② 看到了之后，要多积累，用在自己的代码里，这才是重要的，学以致用，吹的好，最终都要落到行动中
③ 看到逼格高的私发给我，装逼致富的路上一个都不能缺