为构造函数和类以及仅包含单个类的文件一致地编写注释块的最有用/最标准/最不令人惊讶的方法是什么？
然后是文件本身？如果它只包含一个类，这是否需要注释块？哪些细节应该去那里？
我想尽量避免类、构造函数和文件注释块之间的重复。
最佳答案
这在很大程度上取决于您的背景以及与您一起工作的人或跟随您的人的假定技能水平。
如果您发布框架、库或类似的东西，您通常会假设您的用户具有所有技能水平，因此您 可能想要记录尽可能多的琐碎废话，以减少您的社区必须处理的问题的负担。
让我从一个我认为文档可能是一个主要痛苦的例子开始。
你绝对需要什么
如果你想使用 PHPDoc，你需要一个文件 doc 块和另一个 doc 块(通常是类 doc 块)。
那些**需要*拥有 @package标签。其他一切都是可选的。
我想说的是，即使是 @package标签是可选的，因为您可以为项目自动生成它。如果我没记错的话，PHPDoc 甚至可以让您为没有标签的所有内容设置默认包。
对于一般的文档，让我从一个例子开始( 一个更长的例子在末尾 ):
你能解释多少次“uri”的意思:
请注意，对于 getUri它解释了 URI 代表什么(只是为了在我假设的评论中讨论一些内容)而它不在 isAbsUri 中。因为在那里你至少可以说“abs 意味着绝对”两次。
如果您不是开源项目(或需要发布 COMPLETE!!!11eleven api 文档):
我会 强烈建议使用 正确、长且具有描述性的类、变量和方法名称 而不是文档。
在 doc 块中再次写一些东西没有任何好处，因为它是 2011 年，我们有 120 个字符宽的终端和自动完成功能，不再需要为了节省一些字符而缩写所有内容。
我什至认为记录琐碎的事情会伤害您和您的团队 通过强制你把时间浪费在没有人能从中获得值(value)的事情上，你会养成总是编写琐碎的文档而不再阅读它们的习惯。
一个好的注释应该解释为什么做某事，而代码本身应该解释如何而不需要进一步的注释。
我最喜欢的冗余文档示例是这个:
class myClass {
/**
* Constructor
*/
public function __construct() {
}
有些指导方针说你有 到文档 一切你最终让人们一次又一次地陈述显而易见的事情。
这不会增加任何值(value)，但会在阅读代码时浪费时间。
正确命名的示例:
class Person {
/**
* Set a persons weight in Kilogram
*
* @param float $kg Weight in Kilogram
*/
public function setWeight($kg) {}
这段代码很容易记录，因为您需要解释“kg”的含义，因为有些人可能使用不同的系统，而您无法在 google 上搜索“kg”。
我赞成写作
class Person {
/**
* @param float $kilogram
*/
public function setWeight($kilogram) {}
doc 块是多余的，因为调用
setWeight在 Person真的可以期望为一个人设置权重。没必要再写出来。使用 $kgm 作为参数还可以省去在文档中解释它的麻烦，我想说的是，根据您的环境，如果每个人真的不知道测量单位，那么每个人都可能会在谷歌上搜索“公斤”。
@PHPDoc 文档
内联评论:
public function generateReport() {
// get the db connection
$reg = WhateverGlobalStorage::get(“db“);
// auth
if(!$reg->getOne("SELECT view_report FROM USER ...")) {}
// template
$id = $reg->getOne("select ... ");
// render
new ReportTemplate($id); // ...
}
如果这些是单独的“块”，只需将它们移动到描述性命名函数
public function generateReport() {
$this->checkAuthentication();
$template = this->createReportTemplate();
$this->renderReport($template);
}
// Not perfect but at least you can grasp what the method does much quicker
其他资源:
我在一些 session 上就该主题所做的演示文稿的幻灯片:
Slideshare: clean-code-stop-wasting-my-time 还有一些更小的、更老的、咆哮的:
they-told-you-to-document-everything-they-lied 书籍引用:
Clean Code: A Handbook of Agile Software Craftsmanship 
Refactoring: Improving the Design of Existing Code
一个更长的例子
abstract class xyzRequest {
/**
* Initializes this xyzRequest.
*
* Available options:
*
* * logging: Whether to enable logging or not (false by default)
*
* @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance
* @param array $parameters An associative array of initialization parameters
* @param array $attributes An associative array of initialization attributes
* @param array $options An associative array of options
*
* @return bool true, if initialization completes successfully, otherwise false
*
* @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
*/
public function initialize(xyzEventDispatcher $dispatcher, $parameters = array(), $attributes = array(), $options = array()) {
让我们逐行查看该文档告诉您的内容。
(我在这里开玩笑是为了表达我的观点)
* Initializes this xyzRequest.
那么在 xyzRequest 上调用 ->initialize 会初始化该请求吗？真的吗？好吧，如果你这么说!
* Available options:
*
* * logging: Whether to enable logging or not (false by default)
我们被告知第三个参数的选项，而不是第二个或第三个参数，但如果我们知道框架，也许我们知道那些？ (由于我们无法弄清楚 -> initialize 的作用而没有人告诉使用我们可能不那么聪明......)
* @param xyzEventDispatcher $dispatcher An xyzEventDispatcher instance
是的，类型提示就在那里。因此，如果该方法需要“xyzEventDispatcher 实例”，我们需要传入“xyzEventDispatcher 实例”。很高兴知道。
* @param array $parameters An associative array of initialization parameters
* @param array $attributes An associative array of initialization attributes
* @param array $options An associative array of options
好的。所以它不是线性阵列。但是我需要将“初始化参数”传递给我可以想出的“初始化”方法。
仍然不知道我实际上需要在那里传递什么，但只要有记录，它就必须没问题!
* @return bool true, if initialization completes successfully, otherwise false
因此， bool 返回值为“好”的“真”和“坏”的“假”。
* @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
*/
因此，如果在我们执行函数命名时发生错误，则会引发异常？
因此异常用于错误情况。好的。很高兴知道。
关于php - 记录文件、类和构造函数的正确方法是什么？，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/5741955/