Google 出品的 Java 编码规范和编程指南，权威又科学，强烈推荐(28)
7.2 摘要片段
每个类或成员的Javadoc以一个简短的摘要片段开始 。 这个片段是非常重要的 ， 在某些情况下 ， 它是唯一出现的文本 ， 比如在类和方法索引中 。
这只是一个小片段 ， 可以是一个名词短语或动词短语 ， 但不是一个完整的句子 。 它不会以A{@codeFooisa...或Thismethod returns...开头 它也不会是一个完整的祈使句 ， 如Savethe record... 。 然而 ， 由于开头大写及被加了标点 ， 它看起来就像是个完整的句子 。
Tip：一个常见的错误是把简单的Javadoc写成/** @return the customer ID */ ， 这是不正确的 。 它应该写成/** Returns the customer ID. */ 。
7.3 哪里需要使用Javadoc
至少在每个public类及它的每个public和protected成员处使用Javadoc ， 以下是一些例外：
7.3.1 例外：不言自明的方法
对于简单明显的方法如getFoo ， Javadoc是可选的(即 ， 是可以不写的) 。 这种情况下除了写“Returns the foo” ， 确实也没有什么值得写了 。
推荐阅读
- 暴雪|错失DOTA一错再错？曾经的“暴雪出品，必属精品”为啥风光不再？
- 暗区突围|曾被称为“nc出品必属精品”的韩国大厂，如今遭遇三连跪
- 漫威银河护卫队|中日巅峰对决！日本Google Play年度最佳游戏提名，看点十足
- 明日方舟|游戏《明日方舟》决定动画化，由Yostar Pictures影业出品
- 手机游戏|拳头出品依旧值得信赖，英雄联盟手游复刻经典，皮肤可360度观看
- 仙女座|圣衣神话仙女座瞬重生版手办官图公开 万代出品的回锅肉真的不香
- 传统文化|周年庆即将来袭，对比2款周年庆皮肤，周年庆出品，必属精品
- 霰弹枪|剑与远征：废土出品并属精品，耀光终有可用大C！
- 我的世界|我的世界：Java种子新出炉，内陆蘑菇岛算什么，这些种子它不香？
- 暴雪|为何暴雪出品，已经不再是精品？（下）