我们目前正处于一个新项目的开始阶段,并希望(一次)从一开始就尽可能多地发表评论,以帮助未来的发展。
我试图找出在 Eclipse 中使用 phpDoc 的最佳实践,但结果相当渺茫。
您能否分享您在 Eclipse 中使用 phpDoc 注释内容的最佳实践和技巧?
关于应该评论什么以及如何评论没有“真正的标准”,但几乎所有评论他的代码的人都会使用一些标签。
例如,我通常至少使用:
@param type name description
: 用于函数/方法的参数@returns type
: 用于函数/方法的返回值@throws ExceptionType
: 如果函数/方法在某些情况下抛出异常@see ..
. :当我想引用另一个文件或提供更多信息的 URL 时@package
和@subpackage
@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)
无论如何,最重要的是要保持一致:团队中的每个成员都应该以相同的方式发表评论,遵循相同的约定。
至少,我至少会坚持 Eclipse 根据您的代码自动插入的最小 phpdoc 标记。
我要争取的第二个最低级别是让 PhpDocumentor 自己开心。对代码运行 PhpDocumentor 后,在文档的根目录中查找 errors.html 页面。这将列出任何 PhpDocumentor 不喜欢的内容,例如没有文件级文档块。您可以努力将该错误列表降至零。
您可以努力达到的第三个级别是满足 PEAR [1] 的 PHP_CodeSniffer 应用程序中包含的任何一种编码标准。这里的一个缺点是这些标准更具体地关注代码本身,但所有标准都包含有关代码文档的规则。