php - 是否有必要/建议包含 PHP 类的文件和类文档？

Question

我正在努力保持最佳编码实践，并且在编写 Web 应用程序时一直遵循 PHP 的 PEAR 编码标准。我正在使用phpcs然而，为了在编写代码时帮助指导我，我一直在烦恼要为我的 PHP 类包含一个文件文档和一个类文档。

可以找到该规则here :

All class files must contain a "file-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Examples of such docblocks can be found below.

文件文档

/**
* Short description for file
*
* Long description for file (if any)...
*
* LICENSE: Some license information
*
* @category   Zend
* @package    Zend_Magic
* @subpackage Wand
* @copyright  Copyright (c) 2005-2014 Zend Technologies USA Inc. (http://www.zend.com)
* @license    http://framework.zend.com/license   BSD License
* @version    $Id:$
* @link       http://framework.zend.com/package/PackageName
* @since      File available since Release 1.5.0
*/

类文档

/**
* Short description for class
*
* Long description for class (if any)...
*
* @category   Zend
* @package    Zend_Magic
* @subpackage Wand
* @copyright  Copyright (c) 2005-2014 Zend Technologies USA Inc. (http://www.zend.com)
* @license    http://framework.zend.com/license   BSD License
* @version    Release: @package_version@
* @link       http://framework.zend.com/package/PackageName
* @since      Class available since Release 1.5.0
* @deprecated Class deprecated in Release 2.0.0
*/

这两个文档在格式和注释上非常接近，以至于我想知道是否有必要将它们放在同一个类文件中？特别是当每个 PHP 文件实现一个类时，文档级别和类级别的描述将是相同的。 PHP 社区中目前关于此类文档的规定有哪些完善且受人尊重的标准和普遍实践？

Answer 1

编码标准已经朝着要求其中包含类定义的文件应仅包含一个类而不再包含其他内容的方向发展。因此，如果存在每个文件一个类的要求，那么它似乎确实会使文件文档 block 和类文档 block 感觉多余。然而，由于除了 CS 要求之外没有任何东西可以阻止文件中包含其他内容，因此文件仍然需要一种方法来记录自身。

生成的文档通常包含文件本身的文档，而不仅仅是类。文件文档 block 是您控制要在这些文档页面上显示的内容的方式。如果您只是想复制类文档 block 中的内容，这是您的选择，但不是必需的。

如果这个文件中只定义了常量，而常量本身需要自己的文档 block ，我们可能会进行关于它们的对话:-)