Question

我们目前正处于一个新项目的开始阶段，并且希望（从一开始）尽可能多地评论从一开始就帮助未来发展。

我试图找出在Eclipse中使用phpDoc的最佳实践，但结果相当不错。

您能否分享使用phpDoc在Eclipse中评论内容的最佳做法和技巧？

Answer 1

关于应该评论什么以及如何评论没有“真正的标准”，但几乎所有评论他的代码的人都使用了一些标签。

例如，我通常至少使用：

简短描述
可选择一个长描述
@param type name description：用于函数/方法的参数
@returns type：用于函数/方法的返回值
@throws ExceptionType：如果函数/方法在某些情况下抛出异常
@see ..。：当我想引用另一个文件或提供更多信息的URL时
根据项目的结构，我也可以使用@package和@subpackage
另一个在类中有魔术属性时很好（你的IDE无法看到它们，因为它们是在代码中编写的）是@property type $name：它允许Eclipse PDT自动完成，甚至是魔法属性 - 例如，Doctrine使用它。

Eclipse PDT使用大多数代码来帮助您编写（尤其是@param）;但是随意添加Eclipse PDT不使用的一些内容：如果从代码生成文档，它总是有用的; - ）

我能给你的最好的建议是看看一些大的应用程序和/或框架（Zend Framework，Doctrine，...）的源代码，看看它们的代码是怎样的评论 - 很可能他们正在使用被广泛接受的东西。

例如，如果你看一下Zend Framework代码，你可以在类中找到这样的东西：

/**
 * @package    Zend_Cache
 * @subpackage Zend_Cache_Backend
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Cache_Backend_Apc extends Zend_Cache_Backend implements Zend_Cache_Backend_ExtendedInterface

对于方法来说就像这样：

/**
 * Test if a cache is available for the given id and (if yes) return it (false else)
 *
 * WARNING $doNotTestCacheValidity=true is unsupported by the Apc backend
 *
 * @param  string  $id                     cache id
 * @param  boolean $doNotTestCacheValidity if set to true, the cache validity won't be tested
 * @return string cached datas (or false)
 */
public function load($id, $doNotTestCacheValidity = false)

无论如何，最重要的是保持一致：团队中的每个成员都应该以相同的方式发表评论，遵循相同的惯例。

Answer 2

至少，我至少坚持Eclipse根据你的代码自动插入的最小phpdoc标签。

我努力的第二个最低级别是保持PhpDocumentor本身的快乐。一旦针对您的代码运行PhpDocumentor，请在文档的根目录中查找errors.html页面。这将列出PhpDocumentor不喜欢的任何内容，例如没有文件级docblock。您可以努力将错误列表降低到零。

您可以努力达到的第三个级别将满足PEAR [1]中PHP_CodeSniffer应用程序中包含的任何一种编码标准。这里的一个缺点是这些标准更专注于代码本身，但所有标准都包含有关代码文档的规则。

[1] - http://pear.php.net/package/PHP_CodeSniffer

如何在Eclipse中使用PHPdoc

2 个答案: