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

Question

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

• 类的注释块,而不是构造函数
• 构造函数的注释块,而不是类
• 构造函数和类的注释块 - >在这种情况下,每个应该包含哪些细节？

然后文件本身？如果它只包含一个类,是否需要注释块？应该去哪些细节？

我想尽量避免在类,构造函数和文件注释块之间重复.

Answer 1

这在很大程度上取决于您的背景以及与您合作的人或您之后的人的假定技能水平.

如果您发布框架,库或类似的东西,您通常会认为您的用户具有所有技能级别,因此您可能希望记录尽可能多的琐碎废话,以减少社区必须处理的问题.

让我从一个例子开始,我认为文档可能是一个主要的痛苦.

你绝对需要什么

如果你想使用PHPDoc,那么你需要一个文件doc块和另一个doc块(通常是类doc块).

那些**需要*有一个@package标签.其他一切都是可选的.

我走得太远了,说甚至@package标签都是可选的,因为你可以自动为项目生成它.如果我没记错的话,PHPDoc甚至可以为没有标签的所有内容设置默认包.

对于一般的文档,让我从一个例子开始(更长的例子在最后):

你有多少次可以解释"uri"的含义:

请注意,因为getUri它解释了什么URI代表(只是为了在我所假设的评论中有讨论的内容),isAbsUri因为在那里你至少可以说"abs意味着绝对"两次.

如果您不是一个开源项目(或需要发送COMPLETE !!! 11eleven api文档):

我强烈建议使用适当的,长的和描述性的类,变量和方法名称而不是文档.

在doc块中再写一些东西是没有收获的,因为它是2011年,我们有120个char宽的终端和自动完成,没有必要为了节省一些字符而缩写所有内容.

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

一个好的评论应该解释为什么要做的事情,而它自己的代码应该如何解释,而不需要进一步的评论.

我最喜欢的冗余文档示例是这样的:

class myClass {
/**
 * Constructor
 */
public function __construct() {
}

一些指引,说你HAVE记录一切和你结束了人陈述连连明显.

这没有增加任何价值,但在阅读代码时会浪费时间.

正确命名的示例:

class Person { 
/** 
 * Set a persons weight in Kilogram
 *
 * @param float $kg Weight in Kilogram
 */
public function setWeight($kg) {}

此代码很容易记录,因为您需要解释"kg"的含义,因为有些人可能会使用不同的系统而您不能谷歌"kg".

我赞成写作

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

doc块是多余的,因为可以真正期望调用setWeighton Person来设置Person的权重.无需再写出来.

使用$ kilogramm作为参数也可以省去在文档中解释它的麻烦,我会说,根据您的环境,如果他真的不知道测量单位,每个人都可以预期谷歌"千克".

@PHPDoc文档

• 当然,我所有的拙见
• 如果不使用类型提示,请始终使用@param标记.
• 始终使用@return标签
• 根本不要使用@author标签.收集代码所有权更有价值,无论如何信息都在源控制存储库中.
• 如果必须,只使用@copyright标签.我喜欢只有LICENSE文件,但我不是律师,所以可能有必要.

内联评论:

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

其他资源:

我在一些会议上就这个主题发表的演讲的幻灯片: Slideshare: clean-code-stop-wasting-my-time

还有一些小的,年纪稍小的咆哮: they-told-you-to-document-everything-they-lied

书籍参考:

Clean Code: A Handbook of Agile Software Craftsmanship

重构:改进现有规范的设计

一个较长的例子

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初始化该请求？真？好的,如果你这样说的话!

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

我们被告知第三个参数的选项,而不是第二个或第三个参数,但如果我们知道框架,我们可能知道这些参数吗？(因为我们无法弄清楚 - >初始化没有人告诉使用我们可能不那么聪明......)

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

因此,对于"好",布尔返回值为"true",对于"bad",则为"false".

   * @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
   */

因此,如果在执行函数命名时发生错误,则抛出异常？

因此异常用于错误情况.好.很高兴知道.

• 不告诉我return false和异常之间的区别.
• @throws自我很好,因为它增加了信息
• 顺便说一句:为什么这是BOLD而不是@link