javadoc注释中的"HTML"会降低可读性吗？是这样,有什么替代方案？

Question

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

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

所以我尝试在javadoc评论中添加HTML.它看起来更好,但是当我生成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直接从代码中读取它时,它的格式和可读性都很好？

还有任何关于文本评论应该包含的指导方针吗？例如,方法的注释应始终以'This method ..'或其他方式开头.

Answer 1

你的问题没有"正确"的答案,因为它很大程度上取决于你想从javadoc工作中得到什么; 但是,最好将代码本身的符号保持为尽可能简单和整洁,因此这里广泛的HTML是不可取的.

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

更典型的是,这是我目前的活动,要求是在多个地方生成易于阅读的东西,即源代码; 一个独立的文件; 并在诸如eclipse之类的IDE中.Eclipse生成与HTML文档中所需内容相同的几率很低,因此最简单的方法是接受该限制并保持格式最小化.让工具做它所做的事情有很多话要说.

留给它自己的设备,该工具将以新用户熟悉的形式生成某些东西 - 这本身就具有相当大的'易用性'价值.美在旁观者的眼中; 你最喜欢的格式可能对其他人来说是可怕的.

我很困惑你在评论中记录方法原型('pre'行).让工具做到这一点,该工具的好处是阻止手动文档和代码之间的不匹配,你只是给自己更多的维护工作在评论中有一个手动副本.

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

如果您正在团队中工作并希望其他人保持javadoc的质量和一致格式,那么再次使用绝对最小的格式化具有商业意义.让开发人员写出有意义的评论是很困难的,而不会让他们把"br"放在正确的位置.

保持格式简单确实意味着对评论的单词进行更多的工作,以便以一种清晰简洁的方式传达您试图提供的信息而不受重点的影响.要回答你的第二个问题,我不会用"这种方法......"等来填写它.较低的文本量意味着它更容易浏览并被读者吸收.

总之,这样做是有问题的做法(如果你在一个团队中工作,肯定不会这样做),理由如下:

• 源代码的可读性
• 保持一致性和准确性
• 没有其他人搞砸了,工作又回到你身边解决(一次又一次)

专注于在文本中获取正确的信息.用户会更感谢你,而不是它呈现的字体.

希望这可以帮助.