【问题标题】:Documenting PHP, should I copy/paste if I extend a class?记录 PHP,如果我扩展一个类,我应该复制/粘贴吗?
【发布时间】:2010-03-23 18:55:10
【问题描述】:

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

现在我扩展了那个类。在这个新方法(实现)中,我应该重新记录参数和描述,我应该将其留空,还是应该只留下适用于该特定实现的相关注释?

我的目标是让 PhpDoc 生成可读的 API 文档,并遵守约定。

【问题讨论】:

    标签: php phpdoc


    【解决方案1】:

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

    我倾向于将关键的通用语言向上浮动到父方法,但我仍然对当前子方法和孙方法有话要说。子方法与父方法的任何区别,和/或此子方法与其他子方法(来自同一父方法的对等)的任何区别,都是此子方法文档块所需的信息。

    我永远不会从父母那里复制/粘贴某些东西给孩子...相反,我将进一步阐明是什么让孩子成为了他的父母和/或兄弟姐妹。另外,我尝试不对父文档块中的孩子说任何话,因为典型的父子关系是作为一种抽象方式来抽象出需要知道孩子的细节的。

    【讨论】:

    • 因此,如果参数没有更改,则没有必要复制/粘贴参数和返回值,但我应该简单说明孩子的行为/方式,因为它是父类。谢谢。如果我写了 PhpDoc,我会让它向下传递参数并返回值,如果它们没有在孩子的类中指定。
    【解决方案2】:

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

    我要举的第一个例子是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)
    

    在这里,再次复制粘贴;以及父类中的一个小修改,子类中没有重新创建。


    现在,我一般会做什么?

    • 我通常认为开发人员编写 cmets 的频率不够
    • 而且通常忘记更新它们
    • 所以,我尽量让他们的生活更轻松,不要重复 cmets
    • 除非子类中的注释必须与父类中的不同。

    【讨论】:

      猜你喜欢
      • 2011-05-04
      • 2011-02-08
      • 2020-02-06
      • 2017-10-04
      • 2013-07-01
      • 1970-01-01
      • 1970-01-01
      • 2018-08-26
      • 1970-01-01
      相关资源
      最近更新 更多