我们目前正处于一个新项目的开始阶段,希望(这一次)从一开始就尽可能多地发表评论,以帮助未来的发展。
我试图找出在 Eclipse 中使用 phpDoc 的最佳实践,但结果非常有限。
您能分享一下在 Eclipse 中使用 phpDoc 注释内容的最佳实践和技巧吗?
对于应该注释什么以及如何注释,没有“真正的标准”,但是几乎任何注释其代码的人都会使用一些标签。
例如,我通常至少使用:
- 简短的描述
- 可选的长描述
-
@param type name description
:用于函数/方法的参数
-
@returns type
:用于函数/方法的返回值
-
@throws ExceptionType
:如果函数/方法在某些情况下抛出异常
-
@see ..
。 :当我想引用另一个文件或提供更多信息的 URL 时
- 根据项目的结构,我还可以使用
@package
and @subpackage
- 当你在一个类中拥有魔法属性时,另一个很好的选择(它们无法被您的 IDE 看到,因为它们是写在代码中的) is
@property type $name
:它允许 Eclipse PDT 进行自动完成,甚至在魔法属性上也是如此——例如,Doctrine 就使用了它。
其中大部分由 Eclipse PDT 使用来帮助您编码(尤其@param
);但请随意添加一些 Eclipse PDT 未使用的内容:如果您从代码生成文档,它总是有用的;-)
我能给您的最好建议是查看一些大型应用程序和/或框架的源代码(Zend 框架、学说……),看看他们的代码是如何注释的——他们很可能使用的是被广泛接受的东西。
例如,如果您查看 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)
无论如何,最重要的是保持一致:团队中的每个成员都应该以相同的方式发表评论,遵循相同的约定。
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)