在编写"库"类型类时，是否最好总是用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)，我本人(因为代码可以自行记录)。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。。

解决方案

我要说的是，当一个笨拙的人正在查看或者修改代码时，即使没有文档，也没有任何东西可以解释，我们认为这很清楚。

a)始终记录文件。

这将使我们能够使用自动化工具来生成基于Web，基于纸张等的文档，这对于那些并不总是拥有源代码的用户来说可能是无价的。

我之所以选择a，纯粹是因为当我调查一个类时，我喜欢看记录在案的公共方法(使用javadoc或者类似方法)。这使某些事情变得更加清晰。但是每个人都有自己的。

每种公开方法都应记录在案。

这就是我通常会在"我小时候双双上坡"的口头禅，因为只有当老板要求我们这样做时才记录下来……最近，我改变了主意。我认为，当我们在开发开源项目，一个通常被称为的库或者提前知道其他人将不得不与我们提供的接口紧密合作时，为每个公共方法提供详尽的文档至关重要。

文档使可维护的代码成为可能，但是，像任何其他事情一样，当我们应该努力添加功能并通过单元测试时，我们可以改写它并花时间写评论，POD和Wiki。这在《敏捷宣言》中得到了解决(即：面对面的交流比文档更好，依此类推，接口方法也是如此)。

一种)

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

如果是类型，则应提及与之协作的其他类型，以及它是如何实现的。这可以帮助用户以所需的方式浏览文档，而不仅仅是浏览文档而没有任何方向。

一种)

正如其他人提到的那样，我们可以生成文档，并且可以进行维护。

同样，Intellisense可以从告诉方法/属性做什么/是什么中受益。

一种)

预先透彻的文档编制的另一个好处是，可以防止随着时间的流逝，方法行为发生变化。在示例中，我们引用了有关刷新和不关闭流的句子可能很有价值，我想说这一详细程度是该方法的用户需要了解的基本语义。如果未对此进行记录，则该API的更高版本的实现可能无法进行刷新，这可能会导致该方法的用户无法预测的结果。

特别是对于API，确实应记录每个公共方法(和字段)。此外，该方法的文档应足够清晰，信息量足够大，以使可用信息不存在歧义的余地。

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

在大多数情况下，我将Java API规范视为一个出色的示例，但是，我注意到有些部分没有得到充分的文档说明和/或者信息丰富。以DropTarget类为例。它有一个名为" clearAutoscroll()"的方法，该方法的javadoc是：

clearAutoscroll
  
  protected void clearAutoscroll()

clear autoscrolling

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

因此，我的观点是，如果我们正在开发供其他人使用的API，则应明确每种方法，属性等的意图。

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

• 它返回的内容(如果有的话)以及该返回值是以特定单位(英尺，米，度等)为单位的，则应弄清楚。用户应该不得不猜测方法返回的是摄氏度还是华氏度还是开尔文。
• 它需要什么参数以及它们的单位(如果有)
• 该方法的目的以及这些参数和返回值的范围(如果有的话)
• 读者看不见的任何其他内容

作为许多API的用户，我见过好，坏和丑陋。作为许多作家，我很早就开始学习有关提供接口时不够清晰和具体的课程，尤其是当我不得不使用几年前编写的库并且必须仔细研究代码以确定确切的内容时我在写的时候在想。

我认为我们不需要过多地编写文档，也不必认为精心挑选的方法，参数名称等对可读性有很大帮助。但是，当我们编写一种方法时，只需几分钟即可记录下来，甚至可能需要一分钟。我没有令人信服的理由，我看不出不明确公共接口并在需要的地方对其进行记录。也许如果它是一个"可丢弃"的库...。但是我不会写太多。

只是我的两分钱。

任何可公开访问的内容，无论是方法，字段，常量还是我们所拥有的东西，都应记录在案，以使用户或者开发人员(包容性或者顺便说一句)能够在几年后出现并拥有他们需要利用已记录对象的信息。记录使用的准备工作，目的，引发的一切以及使用后的变化。

要清楚明确，不要做任何猜测。如果我们愿意，请向与项目无关的人员显示我们正在记录的内容的声明，并询问他们是否有任何遗漏。做笔记，并确保他们的顾虑得到了解决。

Tout le monde说代码应该是足够好的文档，但这是一个神话。不是每个人都能看到代码，或者意识到我们在其中工作过的巧妙技巧。因此，记录其他人可能看到的所有东西，甚至其他人看不到的东西。用户，开发人员同伴和我们自己将在几年内感谢我们。

始终记录。

对我们而言显而易见的东西可能对其他人而言并不明显，特别是如果他们从不同的角度来看情况(非编码人员，初学者，不熟悉语言结构的用户)

也是为了确保文档的完整性。

对不起，鹦鹉，但始终记录。

始终记录文件，甚至包括私人功能。我已经几次忘记了我所知道的一切。但是在开始时，我评论了所有内容，因此至少很容易再次发现。当我制作一些小型库时，如果没有我做的一些笔记，就记录了我所在团队的所有功能，那么内部工作就完全不可能破译。

我编写了荒谬的复杂代码，以至于我的队友都无法理解。没有人认为它草率或者轻率，但是在详细解释(花费几个小时)之前，没有人会遵循逻辑。当我在纸上写过一次之后，这似乎是对我的显而易见的答案，但是在这一点上，我的逻辑与其他所有人都不同。

因此，我扫描了这篇文章，记录了我所有的功能，并列出了所有需要的输入格式，并写了一个有关该应用程序应如何完成其​​任务的添加文档。我辞去了三年多的工作，而当他们需要特定的东西时(最近是六个月前)，我仍然谈论该软件。它不到一个Kloc(1000行代码)，但仍然足够复杂，足以在两年半后提出问题。

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

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

我们已经写了inStream是InputStream，而不必在函数的注释中指定将其读入字节，因为我们已经在函数的注释中这样做了。

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