Question

我正在努力维护最好的编码实践，并在编写我的Web应用程序时遵循PHP的PEAR编码标准。我在编写代码时使用phpcs来帮助指导我，但是，我正在唠叨为我的PHP类包含文件doc和类doc。

规则可以找到here：

所有类文件必须包含＆＃34;文件级＆＃34;每个文件顶部的docblock和一个＆＃34;类级＆＃34;每个班级上方的docblock。此类文档块的示例可以在下面找到。

档案文件

/**
* 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文件实现一个类时，doc级别和类级别的描述将是相同的。 PHP社区中有哪些成熟且受尊重的标准和通用实践现在就这类文档发出指示？

Answer 1

编码标准已经转向要求其中包含类定义的文件应该只包含一个类而不包含任何其他类。因此，如果这个每个文件一个类的要求存在，那么它似乎确实使文件-docblock-and-class-docblock感到多余。但是，由于CS要求之外的任何内容都不能阻止在文件中包含其他内容，因此该文件仍然需要一种方法来记录自己。

生成的文档通常包含文件本身的文档，而不仅仅是类。文件docblock是您控制要在这些文档页面上显示的内容的方法。如果你只是想在课程docblock中写下什么，那么这是你的选择，但不是必需的。

如果这个文件只在其中定义了常量，它本身需要自己的docblock，我们可能正在讨论它们： - ）

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

1 个答案: