应该记录API的所有公共方法吗？

Question

在编写“库”类型类时，是否最好总是在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似乎是不言而喻的，而且只需要如果funcion在所有改变为更新的干扰。但关于冲洗和不关闭流的话可能很有价值。

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

一）始终记录
二）文档任何不明显
C）从来没有记录（代码应该为自己说话）

！

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

Answer 1

我说，因为当有人谁是钝正在审查或修改代码，什么都不是即使没有文件，你也会这样认为这很清楚。

Answer 2

a）始终记录。

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

Answer 3

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

Answer 4

每个应该记录公共方法。

Answer 5

这就是我通常会在“我小时候双向上坡”时吟诵的咒语，只有当你的老板向你要求时才记录下来，但是......最近我改变了我的曲调。我认为这是至关重要当您正在开发一个开源项目，一个常用库，或者提前知道其他人将不得不与您的接口密切合作时，提供每种公共方法的详细文档正在提供。文档为可维护的代码提供了保证，但是和其他任何软件一样，当你需要增加功能并通过单元测试时，你可以花时间写作注释和POD和维基。这在Agile Manifesto中得到了解决（即：面对面的沟通比文档更好，接口方法也是如此）。

Answer 6

一）

如果它是一个方法，总有一些事一些小细节，比如你提供关于冲洗和关闭流的人。例如，一个“String getFileExtension（String filename）”方法似乎不需要文档，但是如果“filename”没有扩展名？应该记录答案。

如果它是一种类型，它应该提及它与之协作的其他类型，以及它是如何做到的。这有助于用户按照自己想要的方式导航文档，而不是无任何指导地浏览文档。

Answer 7

一）

正如其他人所说，你可以生成文档，并将它与维护有助于。

此外，Intellisense从告诉方法/属性的功能中受益。

Answer 8

一）

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

Answer 9

特别是对于API，每个公共方法（和字段）都应该被记录下来。此外，该方法的文档应该足够清楚和足够丰富，以便可用的信息不留歧义。

API的一个很好的例子是Java API Specification。来自文件标题的通知是规范。我认为文档应该足够彻底，可以将其作为规范来考虑。

大多数情况下，我将Java API规范看作是一个很好的例子，但是，我注意到有一些部分没有很好的文档记录和/或提供信息。以DropTarget班为例。它有一个叫做clearAutoscroll()方法，以及该方法的Javadoc：

clearAutoscroll

protected void clearAutoscroll()

clear autoscrolling 

没有什么比文档更令人沮丧的是无信息的API喜欢这个。最糟糕的是，所提供的信息甚至不是一句话！确保为所有公共字段和方法提供的文档足够丰富，以至于图书馆的用户不会感到恼火，而不会被告知。

Answer 10

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

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

• 它返回什么，如果有的话，如果返回值是在一个特定的单位（英尺，米，度等），那么它应该清楚。用户应该猜测你的方法是否返回摄氏或华氏或开尔文。
• 什么参数需要和什么单位的都在，如果该方法的任何
• 目的和范围对这些参数和返回值，如果是有道理的
• 其他任何不明显的读者

作为很多API的用户，我已经看到了好的，坏的和丑陋的。作为很多作家，我在早期就学到了关于提供接口时不清楚和具体的教训，特别是当我不得不使用我几年前写的一个库时，必须深入研究代码以确定我究竟是什么我在写这本书时正在想。

我不认为你需要在文档上过度使用，并认为精心挑选的方法，参数名称等可以长时间读取。但是当你写一个方法的时候，只需要几秒钟 - 也许一分钟就能完成 - 记录下来。没有令人信服的理由，我可以看到不公开接口，并将其记录在需要它的地方。也许如果它是一个“一掷千金”的图书馆......但我不会写太多的图书馆。

只是我的两分钱。

Answer 11

任何可公开访问的东西，无论是方法，字段，常量还是什么都应该记录下来，以便用户或开发人员（这是一个包容性或btw）能够在几年后出现，并拥有他们需要的所有信息来利用记录的对象。记录使用的先决条件，目的，抛出的内容以及使用后的更改。

要清楚具体，不要留下任何猜测。如果您非常喜欢，请向没有参与项目的人员展示您正在记录的内容的声明，并询问他们是否缺少任何内容。做笔记，并确保涵盖他们的顾虑。

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

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

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