我在Javadocs与谁交谈？

Question

我目前正在进行单一任务。我们必须编写Javadoc注释。我的问题是，我真的不知道我在这里“和谁说话”。

我的项目中对不同方法的评论的一些示例：

• “接下来我们关心的是......的数量。”
• “我们希望从列表中删除这些项目，因为......”

所以问题是：我可以像这样放置Javadocs，还是用正式语言编写它们？我应该在句子中加注谁（如果我可以加入某人）。

Answer 1

完全取决于你/你的团队如何正式或非正式地制作你的Javadoc。

直接向任何人（无论是“你”还是“我们”）发送电话都是相对罕见的，但同样，这是你的电话。考虑一下JDK的文档，它通常是这样的：

  

String类表示字符串。 Java程序中的所有字符串文字（例如"abc"）都实现为此类的实例。

直接，清晰，没有人情味。只是陈述事实。

另一个例子（来自Object#equals）：

  

请注意，一旦覆盖此方法，通常需要覆盖hashCode方法，以便维护hashCode方法的常规协定，该方法声明相等对象必须具有相等的哈希码

请注意它没有说“注意你一般必须覆盖......”它没有告诉任何人做什么，只是注意到如果做X，通常有必要这样做收率

Answer 2

如果您向第三方发布，Javadocs最重要。您不会在场解释您的代码。第三方希望只使用你的课程/担心他们如何履行合同。您的文档应告诉他们需要知道的内容：合同条款是什么。他们需要知道提供什么，期待什么，例外，不变量等等。

我想说在这种情况下保持语言正式。它反映在你身上更好。

您不会像对待朋友一样与第三方沟通。最好保持正规。

我会停止使用“我们”，并以“你”的方式思考更多。这是关于你的图书馆的消费者，而不是开发者。