选择javadoc/phpdoc比定期评论有什么理由和情况？

Question

选择javadoc/phpdoc比定期评论有什么理由和情况？我知道语法差异是什么,但为什么要使用其中一个.它主要是语义还是其他原因我应该使用一个而不是另一个,它们是什么？

我真的不明白javadoc/phpdoc评论的目的.下一个代码块有什么问题？......这/**只是让某些评论在编辑器中变成不同颜色的一种方式...一些编辑不区分(香草崇高似乎不是)？

/*
 * This block is wrapped in /** */ not /* */
 * Some documentation goes here
 * Below is copied from http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */ 

另一个问题......会有任何理由我为什么要同时使用/** */,并/* */在同一个文件？

最后的问题...为什么javadoc/phpdoc评论看起来似乎与类有关...但是我看到它们被用作对我最初理解的页面的介绍评论？

实际上又是另一个......冒着回答我自己的问题的风险我想知道javadoc/phpdoc注释真的只是区分工具自动编写的注释和开发人员编写的注释吗？

Answer 1

人们使用Javadoc的全部原因是为了保持一致性和可读性 - 如果你知道语法,就可以很容易地查看别人的代码(反之亦然),并立即理解其含义.而不是像:

// This method is used for counting sheep just before bed time
// It's really awesome, and takes the bed-time, and also age,
// And also number of sheep, in reverse order.

这需要时间来处理; 它更好看:

/**
 * Count the number of sheep at bedtime
 *
 * @author Tom Walters 
 *
 * @param sheep   The number of sheep to count
 * @param age     The age of the person going to bed
 * @param bedTime The time of going to bed in 24hr format
 * @return The sheep were counted successfully
 */

您可以立即看到有多少参数,以及每个参数的用途.返回类型也是如此.当团队合作让作者在那里工作时,它也非常有用,然后你知道当羊走入歧途时谁会大喊大叫.

至于/**-它有助于区分东西就像是随机的意见,并就行注释这种风格,是一个很好的约定,以帮助的Javadoc伸出浏览代码时.

作为一项规则,您将比编写代码更多地维护代码,因此使用这样一个明确定义的语法是一个好主意 - 它会导致您分配更多时间来考虑解决问题,而不是解密大块文本以获取基本信息.