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

| 为构造器和仅包含一个类的类和文件一致地编写注释块的最有用/最标准/最令人惊讶的方法是什么? 类的注释块,而不是构造函数 构造函数而不是类的注释块 构造函数和类的注释块->在这种情况下,每种注释中应包含哪些详细信息? 然后文件本身?如果仅包含一个类,是否需要注释块?什么细节应该去那里? 我想尽量避免在类,构造函数和文件注释块之间重复。     
已邀请:
这在很大程度上取决于您的背景以及与您一起工作的人或跟随您的人的假定的技能水平。 如果发布框架,库或类似的东西,通常会假设您的用户具有所有技能,因此您可能希望记录尽可能多的琐碎事情,以减少社区必须处理的问题。 让我从一个示例开始,我认为文档可能是一个很大的难题。 你绝对需要什么 如果要使用PHPDoc,则需要一个文件doc块,然后是另一个doc块(通常是class doc块)。 那些*需要*带有“ 0”标签。其他所有都是可选的。 到目前为止,我说即使是
@package
标记也是可选的,因为您可能能够为项目自动生成它。而且,如果我没记错的话,PHPDoc甚至可以为没有标签的所有内容设置默认软件包。 对于一般的文档,让我从一个示例开始(最后是一个更长的示例): 您可以解释多少次“ uri”是什么意思: 请注意,对于
getUri
,它解释了URI的含义(只是在我假设的注释中有话要说),而it3ѭ中则没有,因为在那里您至少可以说“ abs表示绝对”。两次。 如果您不是开源项目(或需要交付COMPLETE !!! 11eleven api文档): 我强烈建议使用适当的,较长的和描述性的类,变量和方法名称代替文档。 在doc块中再写一些东西是没有好处的,因为它是2011年,并且我们有120个字符宽的终端和自动补全功能,因此不再需要为了节省一些字符而缩写所有内容。 我什至会争辩说,记录琐碎的事情会迫使您浪费时间在那些没有价值的事情上,这对您和您的团队都是有害的,因为您养成了总是编写琐碎的文档而不再阅读它们的习惯。 一个好的注释应该说明为什么要做某件事,而代码本身应该说明如何做而无需进一步的注释。 我最喜欢的冗余文档示例是以下示例:
class myClass {
/**
 * Constructor
 */
public function __construct() {
}
一些准则说您必须记录所有内容,最终您会被人们一次又一次地陈述显而易见的内容。 这没有任何价值,但是在读取代码时浪费了时间。 正确命名的示例:
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块是多余的,因为真的可以期望在
Person
上调用
setWeight
来设置人的权重。无需再次写出来。 使用$ kilogramm作为参数还可以避免您在文档中对其进行解释的麻烦,我会说,根据您的环境,如果每个人确实不知道Google的“公斤”,都可以用它来搜索“公斤”测量单位。 @PHPDoc文档 我所有的拙见当然 如果您不使用类型提示,请始终使用@param标记。 始终使用@return标签 根本不要使用@author标记。收集代码的所有权更有价值,并且无论如何信息都在源代码控制存储库中。 如有必要,仅使用@copyright标记。我只喜欢拥有许可文件,但我不是律师,因此可能有必要。 内联评论:
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
以及其他小一点,大一点的:rant12ѭ 书籍参考:
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上调用-> 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
因此,布尔值的返回值为\“ true \”(对于\“ good \”)和\“ false \”(对于Bad \“)。
   * @throws <b>xyzInitializationException</b> If an error occurs while initializing this xyzRequest
   */
因此,如果在执行函数命名时发生错误,则会引发异常? 因此,异常用于错误情况。好。很高兴知道。 不会告诉我return false和异常之间的区别。 @throws自身很好,因为它可以添加信息 顺便说一句:为什么这个大胆而不是一个@link     
就个人而言,我仅在构造函数中有需要注释的地方(例如特殊的初始化)进行注释。 我不会说这是“最有用的”方法,但是它使代码保持整洁,并且实际上不需要重复两次相同的事情(如果那是您的关注) 。     
注释所有内容-文件(作者,版权,描述等),类(描述,代码示例),方法和属性。这是一个带有phpDoc注释的好例子。     
我个人认为类和方法文档是最重要的文档。当我编写代码时,当代码完成向我显示属于某个方法的文档时,我需要我的IDE的帮助。这样,我可以轻松找到所需的方法。 由于我尝试将类的显式初始化保持在最低限度,因此我不使用用户构造函数注释。因此,我尝试避免使用构造函数本身。 方法或函数中的代码应通过使用声明性变量名并使其尽可能小而尽可能清晰。仅当我做一些意想不到的事情时,例如对于集成问题,我才对它们进行评论。     

要回复问题请先登录注册