Question

我有一个带有方法的PHP类。在基类中（它更像是原型，但我不使用原型，因为我们必须向后兼容），我记录了方法的参数和描述。

现在我扩展那个班级。在这个新方法（实现）中，我应该重新记录参数和描述，我应该留空，还是应该只留下适用于该特定实现的相关注释？

我的目标是拥有PhpDoc生成的可读API文档，并遵循惯例。

Answer 1

PhpDocumentor将向您展示所记录的方法是否是父类中方法的重新定义，以及该方法是否在子类中被覆盖。因此，除了放在方法的docblock中的所有信息之外，您还将看到有一个与当前方法关联的父方法和/或子方法。这意味着在方法的docblock中说 something 符合你的利益。

我倾向于将关键通用语言向上移向父方法，但我仍然可以对当前子方法以及孙子方法有所说明。无论子方法与父方法有什么区别，和/或将此子方法与来自同一父方法的其他子方法区别开来的是此子方法docblock所需的信息。

我永远不会把父母的东西复制/粘贴给孩子......我会进一步澄清是什么让孩子与他的父母和/或他的兄弟姐妹有关。此外，我尝试不来对父母的docblock中的孩子说些什么，因为典型的父子关系是为了抽象而不需要知道孩子的具体情况。

Answer 2

查看Zend Framework中的几个示例，似乎评论大多是复制粘贴的 - 这有时会导致不同的评论。

我将采用的第一个例子是Zend_Http_Client_Adapter_Interface::connect，它被声明为：

/**
 * Connect to the remote server
 *
 * @param string  $host
 * @param int     $port
 * @param boolean $secure
 */
public function connect($host, $port = 80, $secure = false);

而且，如果你看一下实现这个界面的类，比如Zend_Http_Client_Adapter_Curl，你会看到：

/**
 * Initialize curl
 *
 * @param  string  $host
 * @param  int     $port
 * @param  boolean $secure
 * @return void
 * @throws Zend_Http_Client_Adapter_Exception if unable to connect
 */
public function connect($host, $port = 80, $secure = false)

所以，复制粘贴的参数;以及实施中的更多信息。

另一个例子是Zend_Log_Writer_Abstract::_write：

/**
 * Write a message to the log.
 *
 * @param  array  $event  log data event
 * @return void
 */
abstract protected function _write($event);

而且，在儿童班中，如Zend_Log_Writer_Db：

/**
 * Write a message to the log.
 *
 * @param  array  $event  event data
 * @return void
 */
protected function _write($event)

这里，再次，复制粘贴;父类中的一个小修改，尚未在子类中重新创建。

现在，我一般做什么？

我一般认为开发人员不经常写评论
通常忘记更新它们
所以，我试着让自己的生活更轻松，不要重复评论
除非子类中的注释必须与父类中的注释不同。

记录PHP，如果我扩展一个类，我应该复制/粘贴吗？

2 个答案: