关于清晰度和 javadoc

Question

对此意见不一......

伙计们，说你有一个方法定义为

public static String getTestName(JsonElement e) throws ParserException;

作为一名想做正确事情的开发人员，我想适当地记录这一点。最初的想法是说：

“返回测试名称的字符串表示”

“真的吗？它返回String？我从方法签名中看到的，你知道的。不用再说了，直接说：

“返回测试名称”

那么它是哪一个？添加“..的字符串表示”有什么价值吗？它会增加清晰度还是噪音？

我报告你决定。

谢谢

Answer 1

为了清楚起见，我会把“字符串”放在那里。事实上，我会考虑让措辞更像“人类可读的字符串”（如果它被设计为人类可读的），或者如果它被设计为由其他软件解析或解释，则以其他方式描述字符串的格式。

最好的方法是考虑下一个开发人员使用此 API 或处理此代码。对于 API 的用户，他们应该能够在不查看代码的情况下获得所需的所有信息。对于开发人员来说，他们应该能够阅读文档（包括代码内文档、生成文档和其他外部文档）并对系统有很好的理解。酌情实现这两个目标。