Documentation 关于clarity和javadoc

在这个问题上意见分歧

伙计们，假设你们有一个定义为

public static String getTestName(JsonElement e) throws ParserException;

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

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

“还是真的？它返回字符串？我从方法签名中看到了这一点，你知道。无需再说一遍，只需说：

“返回测试名称”

那么这是哪一个呢？添加“字符串表示…”是否有任何价值？它是否增加了清晰度或噪音

我报告你决定

谢谢

为了清楚起见，我会把“字符串”放在那里。事实上，我会考虑让措辞更像“人类可读字符串”（如果它被设计成是人类可读的），或者在其他的软件被解析或解释的情况下描述字符串的格式化。 最好的方法是考虑下一个开发人员使用此API或处理此代码。对于API用户，他们应该能够在不查看代码的情况下获得所需的所有信息。对于开发人员，他们应该能够阅读文档（包括代码、生成的文档和其他外部文档）并且对系统有很好的理解。适当地实现这两个目标