关于清晰度和javadoc

Question

意见分歧就此......

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

的方法

public static String getTestName(JsonElement e) throws ParserException;

作为一个想做正确事情的开发者，我想适当地记录下来。最初的想法是说：

“返回测试名称”

的字符串表示形式

“或者真的？它返回String？我从方法签名中看到这一点，你知道。不需要再说一遍，只需说：

“返回测试名称”

那是哪一个？添加“字符串表示形式”是否有任何价值？是否会增加清晰度或噪音？

我报告你决定。

由于

Answer 1

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

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