问注释代码

EN

注释内部方法代码和注释API之间有很大的区别。

对于代码，我不熟悉具体的实践或布局。“使用常识”是最好的。不要在文档中记录任何明显的代码等内容，但要记录所有不能立即清楚的内容。记住，比没有注释的代码更糟糕的一件事是带有过时注释的代码。更多的评论意味着更多的东西需要更新。

对于API文档，有两种方法。文档-详细信息中的所有内容(由Sun提出)，以及更灵活(只提出重要部分)。在许多地方，您不需要记录从签名中明显可见的API内容。

虽然完整的方法文档( sun方法)对于拥有一个充实的规范很重要，但我的研究表明，它使发现重要的警告变得更加困难，可能会导致更多的错误。

有关API，另请参阅：Creating Great API Documentation: Tools and Techniques

Java定义了代码注释标准。尝试此http://www.oracle.com/technetwork/java/codeconv-138413.html

我想这要看情况了，javadoc对于大型项目来说是不错的。如果这是一个小项目或学校作业，在方法头之前做一个小的描述会很好，也许在方法中穿插一些注释，以防你以非正统的方式做事情。然而，在这些之前，我建议你给你的方法起一个信息性的名称，以及变量和参数，这样就更容易推断出方法正在做什么，而不是读取并试图弄清楚每个参数的确切用途，等等。