Php 记录文件、类和构造函数的正确方法是什么？

对于只包含单个类的构造函数、类和文件，一致地编写注释块的最有用/最标准/最不令人惊讶的方法是什么

• 类的注释块，而不是构造函数
• 构造函数的注释块，而不是类
• 构造函数和类的注释块->在这种情况下，每个注释块应该包含什么样的详细信息

那么文件本身呢？如果它只包含一个类，是否需要注释块？应该有哪些细节

---

我想尽量避免类、构造函数和文件注释块之间的重复。

注释所有内容-文件（作者身份、版权、说明等）、类（说明、代码示例）、方法和属性。是一个很好的注释示例。

就我个人而言，我只在构造函数中注释一些特殊的注释（如特殊初始化）

---

我不认为这是“最有用”的方法，但它保持了代码的整洁，并且实际上不需要重复两次相同的事情（如果您担心的话）。

我个人认为类和方法文档是最重要的文档。当我编写代码时，当代码完成向我显示属于某个方法的文档时，我需要IDE的帮助。这样我就可以很容易地找到我需要的方法

因为我试图将类的显式初始化保持在最小值，所以我不需要用户构造函数注释。因此，我尽量避免使用构造函数本身

---

方法或函数中的代码应尽可能清晰，方法或函数中的代码应使用声明性变量名并尽可能小。只有当我做了一些意想不到的事情时，例如集成问题，我才会对其进行评论。

这在很大程度上取决于您的背景以及您的同事或继任者的假定技能水平。

如果你发布了一个框架、一个库或类似的东西，你通常会认为你的用户具备所有的技能水平，因此你可能想要记录尽可能多的琐碎内容，以减少你的社区必须处理的问题的负担

让我从一个例子开始，在这个例子中，我认为文档可能是一大难题

你绝对需要什么 如果您想使用PHPDoc，您需要一个文件doc块和之后的另一个doc块（通常是类doc块）

那些**需要*有一个

@package

标签。其他一切都是可选的

我要说的是，即使是

@package

标记也是可选的，因为您可能能够为project自动生成它。如果我没记错的话，PHPDoc甚至可以为所有没有标签的东西设置默认包

对于一般的文档，让我从一个示例开始（后面是一个较长的示例）：

您可以解释多少次“uri”的含义： 请注意，对于

getUri

，它解释了URI代表什么（只是为了在我假设的评论中有一些东西可以谈论），而它不在

isAbsUri

中，因为在那里你至少可以说两次“abs意味着绝对”

---

如果您不是开源项目（或需要发布COMPLETE！！！11elevenapi文档）：

我建议使用适当的、长的和描述性的类、变量和方法名来代替文档

在doc块中再次写入内容没有任何好处，因为现在是2011年，我们有120个字符宽的终端和自动完成功能，因此不再需要为了节省一些字符而缩写所有内容

我甚至认为，记录琐碎的事情会伤害你和你的团队迫使你在没有人从你身上获得价值的事情上浪费时间，养成总是写琐碎的文档而不再阅读它们的习惯

好的注释应该解释为什么要做某件事，而代码本身应该解释如何做，而不需要进一步的注释。

我最喜欢的冗余文档示例如下： 一些指导方针说，你有来记录一切，结果人们一次又一次地陈述显而易见的事情

这不会增加任何价值，但在读取代码时会浪费时间

正确命名的示例： 这段代码很容易记录，因为你需要解释“kg”是什么意思，因为有些人可能使用不同的系统，你不能用谷歌搜索“kg”

我赞成写作

class Person { 
/** 
 * @param float $kilogram
 */
public function setWeight($kilogram) {}

doc块是多余的，因为在

Person

上调用

setWeight

实际上可以设置一个人的权重。不用再写了

使用$kg作为参数也省去了在文档中解释它的麻烦。我想说，根据您的环境，如果每个人都不知道度量单位，那么可以通过谷歌搜索“kg”

---

@PHPDoc文档

• 当然是我的拙见
• 如果不使用类型暗示，请始终使用@param标记
• 始终使用@return标记
• 根本不要使用@author标记。无论如何，这些信息都在源代码管理存储库中
• 只有在必要时才使用@copyright标签。我只喜欢有一个许可证文件，但我不是律师，所以这可能是必要的

内联注释： 如果这些是单独的“块”，只需将它们移动到描述性命名函数

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

额外资源： 我在一些会议上就这一主题所作的演讲幻灯片：

还有一些小的，老的，咆哮的：

参考书：

一个较长的例子 那么对xyzRequest调用->初始化会初始化该请求吗？真正地好吧，如果你这么说的话

   * Available options:
   *
   *  * logging: Whether to enable logging or not (false by default)

我们被告知第三个参数的选项，而不是

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

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.

   * 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
   */