我目前正在完成一项大学作业。我们必须编写 Javadoc cmets。我的问题是我真的不知道我在和谁“说话”。
我项目中cmets到不同方法的一些例子：
所以问题是：我可以这样放置 Javadocs 还是必须用正式语言编写它们？我在句子中称呼谁（如果我可以称呼某人）。
【问题讨论】：
标签： java documentation comments javadoc
制作 Javadoc 的正式或非正式程度完全取决于您/您的团队。
直接与任何人（无论是“您”还是“我们”）联系的情况相对较少，但同样，这是您的决定。考虑一下 JDK 的文档，它通常是这样的：
String类表示字符串。 Java 程序中的所有字符串字面量，例如"abc"，都是作为此类的实例实现的。
直接、清晰、客观。只需陈述事实即可。
另一个例子（来自Object#equals）：
请注意，当
hashCode方法被重写时，通常需要重写此方法，以维护hashCode方法的一般约定，即相等的对象必须具有相等的哈希码。
注意它没有说“注意你通常必须覆盖......”它没有告诉任何人该做什么，只是指出如果做X，通常有必要做是的。
【讨论】：
如果您要向第三方发布，Javadocs 最重要。您不会在场解释您的代码。第三方将只想使用您的课程，而不必担心他们如何履行合同。你的文件应该告诉他们他们需要知道什么：合同条款是什么。他们需要知道要提供什么、期望返回什么、异常、不变量等。
我会说在这种情况下保持语言正式。它更好地反映在你身上。
您与第三方交流的方式与与朋友交流的方式不同。最好保持正式。
我会停止使用“我们”，而更多地考虑“你”。这是关于你的图书馆的消费者，而不是开发者。
【讨论】：