9

在 javadoc 注释中使用 HTML 是好还是坏？

当我查看 java 方法的注释时，它们的格式看起来都很好，顶部是方法的名称，然后是整个方法头，但是当我将 javadoc 添加到我的方法时，它几乎不可读（我的意思是使用时弹出的信息编写代码时的自动完成）。

所以我尝试将 HTML 添加到 javadoc 注释中。它看起来更好，但是当我生成 javadoc 并查看浏览器中的注释时，布局全乱了。

当直接在代码中阅读时，添加 HTML 会使我的评论难以阅读。

我的评论示例：

/**
* <br/>
* <li><b><i>hasChanged</i></b></li>
* <br/><br/><br/>
* 
* <pre>public void hasChanged(boolean changed)</pre>
* <br/>
* 
* This method can notify the observers when a change has occurred in a model.
* <br/><br/>
* 
* The observer can then set the right controls
* <br/><br/>
* 
* @param changed
* <br/><br/>
* Pass true if a model has been changed from it's starting values <br/><br/>
* Pass false if the model has it's initial values<br/><br/>
*/

是否有一些最佳实践如何在 java 中编写注释，以便它可以从浏览器中的 javadoc 中很好地格式化和读取，就像直接从代码中读取它一样？

还有关于文本评论应该包含的任何指导方针吗？例如，方法的注释应始终以“此方法..”或其他内容开头。

4

1 回答 1

7

您的问题没有“正确”答案，因为这在很大程度上取决于您希望从 javadoc 工作中得到什么；然而，保持代码本身的符号尽可能简单和整洁是一种很好的做法，因此这里不建议使用大量HTML。

如果您的目标是生成高质量的独立 HTML 文档；特别是如果它正在记录一个源代码不存在的库，那么源代码中的 HTML 中广泛的显式格式可能是一种有用的技术。

更典型的是，这是我目前的活动，要求是生成在多个地方易于阅读的东西，即源代码；独立文件；并在诸如eclipse之类的IDE中。Eclipse 从 HTML 文档中生成与您想要的内容相同的可能性很低，因此接受该限制并保持格式最小化是最简单的。让工具完成它的工作有很多话要说。

留给它自己的设备，该工具将以新用户熟悉的形式产生一些东西——这本身就具有相当大的“易用性”价值。美在旁观者的眼中; 您喜欢的格式可能对其他人来说是可怕的。

我对您在评论中记录方法原型（“前”行）感到困惑。让工具来做这件事，工具的好处是阻止手动文档和代码之间的不匹配，你只是在注释中给自己更多的维护工作。

保持格式简单的一个好处是它使源代码注释在原位易于阅读。这使得它们更有可能被开发人员准确维护。

如果您在一个团队中工作并希望其他人保持 javadoc 的质量和一致的格式，那么再次使用绝对最小的格式具有商业意义。如果不让开发人员也将“br”放在正确的位置，就很难让开发人员写出有意义的评论。

保持格式简单确实意味着对评论的文字做更多的工作，以便以一种清晰简洁的方式传达您试图提供的信息，而无需强调。为了回答你的第二个问题，我不会用“这种方法......”等来填充它。文本量较少意味着它更容易被读者浏览和接受。

总之，这样做是有问题的做法（如果你在一个团队中工作，绝对不要这样做），原因如下：

  • 源代码的可读性
  • 保持一致性和准确性
  • 不要让其他人把它搞砸，工作会回到你身边来解决它（一次又一次）

专注于在文本中获取正确的信息。用户会为此感谢你，而不是因为它呈现的字体。

希望这可以帮助。

于 2013-08-08T09:05:27.367 回答