9

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

/**
 * 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)，我自己（因为代码可以是自记录的，否则）...

4

15 回答 15

18

a) 始终记录。

这将允许您使用自动化工具来生成基于 Web 的、基于纸张的等文档，这对于并不总是在他们面前的源代码的用户来说可能是无价的。

于 2008-09-25T02:12:18.993 回答
3

这就是我通常会附和“我小时候双向上坡”的口头禅，即只有当你的老板要求你记录时才记录......最近我改变了我的态度。我认为当你在处理一个开源项目、一个通常被调用的库或者提前知道其他人必须与你提供的接口密切合作时，提供每个公共​​方法的完整文档是至关重要的.

文档有助于编写可维护的代码，但是，就像任何事情一样，当您应该致力于添加功能并让单元测试通过时，您可以过度使用它并花时间编写评论、POD 和 wiki。这在敏捷宣言中得到了解决（即：面对面的交流比文档更好，等等接口方法的阶梯）。

于 2008-09-25T02:21:50.423 回答
3

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

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

在大多数情况下，我认为 Java API 规范是一个很好的例子，但是，我注意到有些部分没有很好的文档和/或信息。以DropTarget班级为例。它有一个名为 的方法clearAutoscroll()，该方法的 javadoc 是：

clearAutoscroll

protected void clearAutoscroll()

clear autoscrolling

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

于 2008-09-25T02:37:23.757 回答
2

一个）

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

此外，Intellisense 受益于告诉方法/属性做什么/是什么。

于 2008-09-25T02:31:59.040 回答
2

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

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

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

作为许多 API 的用户，我见过好的、坏的和丑陋的。作为许多人的作者，我很早就吸取了教训，即在提供接口时不够清晰和具体，尤其是当我不得不使用几年前编写的库并且必须深入研究代码以确定我的确切内容时写的时候在想。

我不认为你需要过分关注文档并认为精心挑选的方法、参数名称等对可读性有很大帮助。但是当你编写一个方法时，只需要几秒钟——也许最多一分钟——来记录它。我看不出有什么令人信服的理由不让公共界面清晰明了，并在需要的地方记录下来。也许如果它是一个“一次性”图书馆......但我不会写太多这些。

只是我的两分钱。

于 2008-09-25T02:48:18.597 回答
1

我想说的是，当一个迟钝的人正在审查或修改您的代码时，没有什么可以解释的，即使没有文档，您也认为它非常清楚。

于 2008-09-25T02:11:43.193 回答
1

我选择 a，纯粹是因为当我研究一个类时，我喜欢查看记录在案的公共方法（在 javadoc 或类似中）。它使一些事情变得更加清晰。但各有各的。

于 2008-09-25T02:13:37.073 回答
1

一个）

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

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

于 2008-09-25T02:25:53.300 回答
1

一个）

预先完整文档的另一个好处是有助于防止方法行为随着时间的推移而发生变化。在示例中，您引用了有关刷新而不关闭流的句子可能很有价值-我想说这种详细程度是该方法的用户需要知道的基本语义。如果这没有记录在案，那么 API 的后续实现可能不会执行刷新，这可能会导致该方法的用户出现不可预测的结果。

于 2008-09-25T02:35:14.120 回答
1

任何可公开访问的内容，无论是方法、字段、常量还是您拥有的东西，都应记录到用户或开发人员（这是一个包容性或顺便说一句）将能够在几年后出现并拥有所有内容的程度他们需要使用文档化对象的信息。记录使用的先决条件、目的、抛出的任何东西以及使用后的变化。

明确而具体，不要留下任何猜测。如果您愿意，请向与您的项目无关的人展示您正在记录的内容的声明，并询问他们是否缺少任何内容。做笔记，并确保他们的担忧被覆盖。

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

于 2008-09-25T05:02:01.537 回答
0

始终记录。

对您来说显而易见的事情对其他人可能并不明显，尤其是当他们从不同的角度看待情况时（非编码人员、初学者、不熟悉您的语言结构的用户）

也是为了文档的完整性。

于 2008-09-25T14:29:46.850 回答
0

对不起鹦鹉，但总是记录。

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

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

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

于 2008-09-29T00:16:43.910 回答
0

每个公共方法都应记录在案。

于 2008-09-25T02:15:19.317 回答
0

b) 记录所有不明显或有疑问的内容。在这种情况下：

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

您已经写过 inStream 是一个 InputStream，并且您不必指定它要在自己的注释中读取字节，因为您已经在函数的注释中这样做了

于 2008-10-11T07:34:47.583 回答
0

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

于 2008-10-11T07:46:14.547 回答