代码注释

Question

4

什么是最专业和信息丰富的代码注释方式？有没有相关的标准呢？

附注：不一定需要使用javadoc，只需提供包括哪些内容的信息即可，例如常见的布局等。

谢谢大家。

- dr85

1

尝试这些问题：https://dev59.com/A0jSa4cB1Zd3GeqPBwWv 和 https://dev59.com/V3A65IYBdhLWcg3w1SVC。 - msarchet

6个回答

1

- Sid

1

我认为这取决于情况，对于大型项目来说，Javadocs非常好用。如果是小型项目或学校作业，方法头前的简短描述就足够了，也可以在方法内插入一些注释，以防您使用了不正规的方法。但在此之前，我建议您给方法、变量和参数起一个有意义的名称，这样比阅读并尝试弄清楚每个参数的用途更容易推断出方法正在做什么。

- Jesus Ramos

1

Steve McConnel的书《代码大全》 - 无疑是关于如何编写软件的最佳书籍之一 - 其中有一个完整的章节介绍如何编写注释和确保您的代码易于理解 - 称为“自我记录代码”。

- DJClayworth

0

我曾经被教导使用前置条件、后置条件，并注释每个方法将修改哪个数据结构。这是在学校里。但我从未见过在工业界中有人这样做。

- Steve

0

- Penkov Vladimir

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Uri · Accepted Answer

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

对于代码，我不熟悉具体的实践或布局。"运用常识"是最好的方式。不要记录任何从代码中显而易见的内容等，但记录所有不立即清晰的内容。请记住，比没有注释的代码更糟糕的是带有过时注释的代码。注释越多意味着需要更新的内容也就越多。

对于API文档，有两种方法。一种是文档化所有细节（由Sun提出），另一种则更加敏捷（只提出重要部分）。在许多地方，您不需要记录API签名中显而易见的内容。

虽然完整的方法文档（Sun方法）对于拥有完善的规范非常重要，但我的研究表明它使得发现重要警告更加困难，可能会导致更多的错误。