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

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的,基于纸张的文档,这对于并非始终在其前面具有源代码的用户而言可能是非常宝贵的.