Question

在编写“库”类型类时，最好总是在java中编写标记文档（即javadoc）或假设代码可以“自我记录”吗？例如，给定以下方法stub：

/**
 * Copies all readable bytes from the provided input stream to the provided output
 * stream.  The output stream will be flushed, but neither stream will be closed.
 *
 * @param inStream an InputStream from which to read bytes.
 * @param outStream an OutputStream to which to copy the read bytes.
 * @throws IOException if there are any errors reading or writing.
 */
public void copyStream(InputStream inStream, OutputStream outStream) throws IOException {
    // copy the stream
}

javadoc似乎是不言而喻的，如果功能完全改变，只需要更新噪音。但关于冲洗而不关闭流的句子可能很有价值。

因此，在编写库时，最好是：

a）始终记录文件 b）记录任何不明显的内容 c）永远不要记录（代码应该说明一切！）

我通常使用b），我自己（因为代码可以自我记录）...

Answer 1

a）始终记录。

这将允许您使用自动化工具生成基于Web的，基于纸张的文档，这对于并非始终在其前面具有源代码的用户来说可能是非常宝贵的。

Answer 2

这就是我通常会在“我小时候双向上坡”的咒语中，只有当你的老板问你但是最近我改变了我的调子时才会记录。当你正在开发一个开源项目，一个通常被调用的库，或提前知道别人必须工作时，我认为提供每个公共方法的详细文档至关重要与您提供的接口密切相关。

文档提供了可维护的代码，但是，就像任何事情一样，当你应该致力于添加功能并让单元测试通过时，你可以过度使用它并花时间编写注释和POD和wiki。这在Agile Manifesto中得到解决（即：面对面的沟通比文档更好，依赖于接口方法的阶梯）。

Answer 3

特别是对于API，确实应该记录每个公共方法（和字段）。此外，该方法的文档应足够清晰，信息量足以使可用信息不会产生歧义。

API的一个很好的例子是Java API Specification。请注意文档标题中的规范。我认为文档应该足够彻底，可以将其视为规范。

在大多数情况下，我将Java API规范视为一个很好的例子，但是，我注意到有些部分没有详细记录和/或提供信息。以DropTarget类为例。它有一个名为clearAutoscroll()的方法，该方法的javadoc是：

<强> clearAutoscroll

protected void clearAutoscroll()
clear autoscrolling

没有什么比这样没有信息的API的文档更令人沮丧了。最糟糕的是，所提供的信息甚至不是一句话！确保为所有公共领域和方法提供的文档足够信息，以便库的用户不会被激怒而不是被告知。

Answer 4

a）

正如其他人所提到的，您可以生成文档，它有助于维护。

此外，Intellisense可以从告诉方法/属性的作用中获益。

Answer 5

所以，我的意见是，如果你正在开发一个供其他人使用的API，那么应该清楚每个方法，属性等的意图。

我应该能够看一个方法并知道：

它返回的内容，如果有的话，如果返回值是特定单位（英尺，米，度等），则应该清楚。用户应该猜测您的方法是否返回摄氏或华氏或开尔文。
它需要什么参数以及它们所在的单位（如果有的话）
这些参数和返回值的方法和范围的目的，如果有意义
对读者来说不明显的任何其他内容

作为许多API的用户，我看到了好的，坏的和丑陋的。作为很多人的作者，我早就吸取了关于在提供界面时不清楚和具体的经验，尤其是当我不得不使用我几年前编写的库时，我不得不深入研究代码来确定我的确切内容。在写这篇文章时我在想。

我认为你不需要过分关注文档，并认为精心挑选的方法，参数名称等在可读性方面走得很远。但是当你编写一个方法时，只需要几秒钟 - 也许一分钟 - 就可以记录它。没有令人信服的理由我可以看到不清楚公共界面并将其记录在需要的地方。也许如果它是一个“一次性”的图书馆....但我不会写太多这些。

只是我的两分钱。

Answer 6

我会说，因为当有人在审视或修改你的代码时，没有任何东西需要解释，即使没有文档，你也认为它非常清楚。

Answer 7

我选择了一个，纯粹是因为当我调查一个类时，我喜欢看到记录的公共方法（在javadoc或类似的中）。它使一些事情变得更加清晰。但每个都是他们自己的。

Answer 8

A）

如果这是一种方法，总会有一些重要的细节，例如你提供的有关刷新和关闭流的细节。例如，方法“String getFileExtension（String filename）”似乎不需要文档，但是如果“filename”没有扩展名怎么办？答案应记录在案。

如果它是一种类型，它应该提到它与之合作的其他类型，以及它是如何做到的。这有助于用户以您想要的方式浏览文档，而不仅仅是在没有任何指导的情况下浏览文档。

Answer 9

A）

前期全面文档的另一个好处是有助于防止方法行为随时间发生变化。在这个例子中，你引用关于刷新的句子而不关闭流可能是有价值的 - 我会说这个细节级别是该方法的用户需要知道的基本语义。如果没有记录，那么API的后续实现可能不会执行刷新，这可能导致方法用户的不可预测的结果。

Answer 10

任何公开可访问的内容，无论是方法，字段，常量还是有什么内容，都应该记录在一起，以便用户或开发人员（包括或者，顺便说一句）能够在几年之后出现，并拥有使用所记录对象所需的所有信息。记录使用的先决条件，目的，抛出的任何内容以及使用后的更改。

要清楚明确，不要做任何猜测。如果您如此倾向，请向未参与项目的人展示您所记录的内容的声明，并询问他们是否遗漏了任何内容。做笔记，并确保他们的担忧得到满足。

Tout le monde说代码应该是足够好的文档，但这是一个神话。不是每个人都能看到代码，或者意识到你在其中运用了什么巧妙的技巧。因此，记录其他人可能看到的所有内容，甚至是他们不会看到的内容。您的用户，开发人员和您自己在几年内会感谢您。

Answer 11

应记录每个公共方法。

Answer 12

始终记录。

对你来说显而易见的事情对其他人来说可能并不明显，特别是如果他们从不同的角度看待这种情况（非编码人员，初学者，不熟悉你的语言结构的用户）

也是为了完整的文档。

Answer 13

抱歉鹦鹉，但总是记录。

始终记录，甚至是您的私人功能。我已经忘记了几次我知道的一切。但是在开始时我评论了所有内容，所以至少很容易弄清楚。当我创建一些小型库时，我记录了我所在的团队的所有功能而没有我做的一些注释，内部工作完全不可能破译。

我写了一些非常复杂的代码，这样我的队友都无法理解。没有人认为它草率或不优雅但在详细解释之前（花费几个小时）没有人可以遵循逻辑。我在纸上写了一次后，对我来说似乎是明显的答案，但在这一点上，我的逻辑对其他人来说都是陌生的。

所以我扫描了论文，记录了我的所有功能，并列出了所有需要的输入格式，并编写了一个关于应用程序应该如何完成其任务的附加文档。我退出这项工作超过3年，当他们需要特定的东西（最近6个月前）时，我仍然会谈论这个软件。它不到Kloc（1000行代码），但它仍然足够复杂，可以在2年半之后提出问题。

Answer 14

b）记录所有不明显或有疑问的事项。在这种情况下：

/** Copies all readable bytes from inStream to outStream. outStream will be flushed, 
 *  but neither stream will be closed.
 */

您已经写过，inStream是一个InputStream，您不必指定它在自己的注释中读取字节，正如您在函数的注释中所做的那样

Answer 15

仅记录您希望人们能够使用并有效使用的那些方法。

是否应记录API的所有公共方法？

15 个答案: