在评论中标注方法的首选方式是什么？答案

【问题标题】：What is the preferred way of notating methods in comments?在评论中标注方法的首选方式是什么？
【发布时间】：2009-06-11 16:55:35
【问题描述】：

有时评论时必须参考另一种方法。这里有一些 PHP 示例：

class A
{
    /**
     * @see B::bar
     */
    public function foo()
    {
        B::bar();
    }
}

class B
{
    public static function bar()
    {
        // ...
    }
}

那么如果在类B 中有一个非静态方法bar 呢？在 cmets 中命名其他方法的最佳方式是什么？

编辑

PHP 手册似乎使用了mysqli->affected_rows 和PDO::beginTransaction。但它不包含方法名称后的括号。这里的利弊是什么？我的意思是一个方法后面跟括号是很明显的，那么为什么不把它们放在外面呢？

提前谢谢！

【问题讨论】：

标签： php naming-conventions comments naming comment-conventions

【解决方案1】：

您可以使用-> 运算符来引用实例/对象方法而不是类方法。 PHP.net 在他们的手册中也这样做了（例如，参见 MySQLi class）。

【讨论】：

谢谢！但即使是官方的 PHP 文档也不一致。例如。 docs.php.net/manual/en/book.pdo.php 使用 :: :/
我很震惊，很震惊我告诉你在 PHP 中的不一致;)

【解决方案2】：

我会写：

class A {
    // see B::bar()
    public function foo() {
        B::bar();
    }
}

关于我的各种变化，我最强烈的看法是信箱 cmets 是魔鬼的作品。关于您的静态与非静态的东西，我理解并使用B::bar() 来指代用于会话目的的函数定义，无论bar() 是否是静态的。

当然，上面的示例仅用于说明目的，因为如果实际上有一个函数 A::foo() 只调用 B::bar()，我不会包含注释，因为如果阅读我的代码的人是白痴，我不想帮助他。

【讨论】：

1.谢谢！ 2. 对不起，我不是母语人士。什么是“信箱评论”？
我所说的信箱 cmets 是指您使用 /* */ 并且左边框为 * 字符的那些。真正令人震惊的有大量的星号顶部和底部边界（如果你相信的话，有时甚至是右边界）。我讨厌正常的人，就像你在你的例子中那样，主要是因为他们让我想起了那些令人震惊的人。
DocBlock cmets 不是个人编码风格问题，而是phpDocumentor 能理解的格式。它的功能目的很像 Perl 的 Pod，并且是一个很好的标准。不幸的是，它可能会冒犯一些程序员的个人编码风格，正如混乱所指出的那样。但是，PEAR 和 Zend 编码风格指南中需要 phpDoc DockBlocks，并且每个遵循标准的程序员有时都必须对自己的风格做出一些让步。见：manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/…

【解决方案3】：

在我看来，你的例子就足够了。不过，您应该将 B::bar 称为 B::bar()。

您可能需要考虑使用@uses php-doc tag，它会在为 B::bar() 生成的文档中自动创建一个 @usedby 引用，指向 A 类。

/**
 * @uses B::bar()
 */

就文档而言，静态方法与@uses、@usedby 或@see 无关，仅与@static 相关。 @uses 标记中的静态符号只是传达寻找 bar() 方法的范围，而不是表示 @static。

【讨论】：

【解决方案4】：

phpDocumentor 的文档似乎暗示您可以使用类似的东西

class A
{
  /**
   * @see B
   * @see function bar()
   */
  public function foo()
  {
    // ...
  }
}

同样来自phpDocumentor manual：

@uses 与@see 非常相似，请参阅 @see 的文档以了解有关的详细信息格式和结构。 @uses 标签与@see 在两个方面不同。 @see 是单向链接，意味着包含 @see 标记的文档包含指向其他的链接文档。 @uses 标签自动创建一个虚拟其他文档中的 @usedby 标签链接到文档包含@uses 标签。其他换句话说，它和@see 完全一样，除了自动添加返回链接。

【讨论】：