在javadoc评论中使用HTML是好的还是坏的做法？
当我查看java方法的注释时，它们看起来很好地使用顶部的方法名称，然后是整个方法头，但是当我将javadoc添加到我的方法时，它几乎不可读（我的意思是弹出的信息）在编写代码时使用自动完成功能时。
所以我尝试在javadoc评论中添加HTML。它看起来更好，但是当我生成javadoc并查看浏览器中的注释时，布局就搞砸了。
在代码中直接阅读HTML时，添加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直接从代码中读取它时，它的格式和可读性都很好？
还有任何关于文本评论应该包含的指导方针吗？例如。方法的注释应始终以“This method ..”或其他内容开头。
答案 0 :(得分：7)
你的问题没有'正确'的答案，因为它在很大程度上取决于你对javadoc工作的要求;但是，最好将代码本身的符号保持尽可能简单和整洁，因此这里广泛的HTML inadvisable 。
如果您的目标是制作质量好，独立的HTML文档;特别是如果它记录了一个不存在源代码的库，那么源代码中HTML中广泛的显式格式化可能是一种有用的技术。
更典型的是，这是我当前的活动，要求是在多个地方生成易于阅读的内容，即源代码;一个独立的文件;并在诸如eclipse之类的IDE中。 Eclipse生成与HTML文档中所需内容相同的几率很低，因此最简单的方法是接受该限制并保持格式最小化。让工具做它所做的事情有很多话要说。
留给它自己的设备，该工具将以新用户熟悉的形式生成某些东西 - 这本身具有相当大的“易用性”价值。美在旁观者的眼中;你最喜欢的格式可能对其他人来说是可怕的。
我对你在评论中记录方法原型（'pre'行）感到困惑。让工具做到这一点，该工具的好处是阻止手动文档和代码之间的不匹配，你只是给自己更多的维护工作在评论中有手动副本。
保持格式简单的一个好处是它使源代码注释易于原位读取。这使得他们更有可能被开发人员精确维护。
如果您在团队中工作并期望其他人保持javadoc的质量和一致格式，那么再次使用绝对最小的格式化具有商业意义。让开发人员写出有意义的评论是很困难的，而不会让他们把“br”放在正确的位置。
保持格式简单意味着对评论的单词进行更多的工作，以便以一种清晰简洁的方式传达您尝试提供的信息，而不会受益于重点。要回答你的第二个问题，我不用“This method ...”等填写它。较低的文本量意味着它更容易浏览并被读者吸收。
总之，这样做是值得怀疑的（如果你是在团队中工作，那肯定不会这样做）原因如下：
专注于在文本中获取正确的信息。用户会更感谢你，而不是渲染它的字体。
希望这有帮助。