关于一个 Javadoc 风格的讨论，@param、@return 是否允许空描述，即是否必须总是有描述信息

[passerbytiny]

有疑问的代码

    /**
     * ……
     * 
     * @param deviceNo
     * @return
     */
    public static EmbeddedChannel createChannel(String deviceNo) {
        // ....
    }

如果没有特别需要的额外说明，那么 deviceNo 一目了然就是指设备号码，写成 @param deviceNo device no 或 @param deviceNo 设备编号感觉就是脱裤子放屁。@return 同理。

然而 Google Java Style 只给 getFoo 这种方法做宽松限制，不给 @param @return 做。

Javadoc is optional for "simple, obvious" methods like getFoo, in cases where there really and truly is nothing else worthwhile to say but "Returns the foo".

Javadoc 对于像 getFoo 这样的“简单、明显”的方法是 可选的，在这种情况下除了“返回 foo ”之外真的没有什么值得说的。

Any of the standard "block tags" that are used appear in the order @param, @return, @throws, @deprecated, and these four types never appear with an empty description.

使用的任何标准“块标记”都以 @param、 @return、 @throws、 @deprecated 的顺序出现，并且这四种类型永远不会出现空描述。

[guyeu]

方法声明做到准确达意并不适用于一切场合；
Javadoc 不光是阅读代码的时候会用到，Javadoc 更重要的意义在于可以导出成为 API 文档，这种时候，声明方法的代码有可能会被省略，所以 javadoc 的规范里才会强制性要求不要出现空描述。
对于没有这种需求的场景，就没有必要遵守这种规范，简单在方法上写点注释即可。

[geelaw]

设备编号一般是 deviceId 才对（假设没有一个 dedicated 设备标识符的概念的话）。

没什么可写就可以不写。从整个文档的角度看读者可能是熟知什么是 deviceId 的，但是从这个有限的上下文看，很容提出一个自然的问题：deviceId 是如何获得的？

[passerbytiny]

@guyeu #1 即使导出 API 文档，文档上也首先显示的是方法签名，而且 @param 只是省略 @param deviceNo {device no} 最后那个文字描述，字段名部分不省略。另外 Javadoc 导出的 API 文档就是个典型的“没人看的”文档，迄今为止只有 java 6 的 chm 格式管用，html 格式的 Javadoc 连快速定位类都办不到。我现在看文档的顺序是：Develop Guide -> 源码。

@geelaw #2 我这只是举了个例子，原始代码中是有额外说明的。现在我要解决的是，要不要在代码风格检查工具中设置为强制规则。如果强制的化，总有可能遇到加上就是脱裤子放屁的描述信息；如果不强制的化，就要找出一个打破代码风格的理由。

[xiangyuecn]

导入到 android studio 中的老代码，看起来就像一坨 si 一样，滚动条密密麻麻的黄色警告，这种提醒关也不是不关也不是

[Cbdy]

否，建议你看看 JDK 源码怎么写的

[passerbytiny]

@xiangyuecn 这应该是你的 IDE 配置或导入方法的问题吧，IDE 干嘛要吃饱了撑地去检查 jar 包中的源代码

[passerbytiny]

今天开始正式动 checkstyle 规则了，才发现谷歌做得是更宽的限制，“ Method Javadoc ” 中，allowMissingParamTags、allowMissingThrowTags、allowMissingReturnTags 全部是勾上的。

我在这里认为 “@param deviceNo device no ” 是脱裤子放屁，人家起始定义的是 “@param ”自身就是脱裤子放屁。

然而根据 Eclipse 的模板配置，要省略 “@param ” 就要多一个 “ Ctrl + D ”的操作，比较蛋疼。