代码之家 › 专栏 › 技术社区 › Philippe Gerber

在评论中记录方法的首选方法是什么?

comment-conventions naming comments naming-conventions php

Philippe Gerber · 技术社区 · 15 年前

有时评论时必须引用另一种方法。下面是一些PHP示例:

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

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

那么如果有一个非静态的方法呢 bar 课堂上 B ? 在注释中命名其他方法的最佳方法是什么?

编辑

PHP手册似乎使用 mysqli->affected_rows 以及 PDO::beginTransaction . 但它不包括方法名称后面的括号。什么是赞成和反对?我的意思是很明显一个方法后面跟着括号,那么为什么不把它们放在外面呢?

提前谢谢!

4 回复 | 直到 13 年前

NullUserException Mark Roddy 13 年前

你可以用 -> 运算符引用实例/对象方法而不是类方法。php.net也会在手册中这样做(请参见 MySQLi class 例如)。

chaos 15 年前

我会写:

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

关于我的各种变化,我最坚定的观点是信箱评论是魔鬼的工作。关于你的静态与非静态,我理解并使用 B::bar() 为会话目的参考函数定义,无论是否 bar() 是静态的。

当然,上面的示例仅用于说明目的,因为如果实际上有一个函数 A::foo() 除了打电话什么都没做 B::() ,我不包括评论,因为如果读我代码的人是个白痴,我不想帮助他。

racerror 15 年前

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

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

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

就文档而言,静态方法与@uses、@usedby或@see无关,仅与@static有关。@uses标记中的静态表示法只传递查找bar()方法的作用域,而不是表示@static。

Alex Basson 15 年前

phpdocumentor的文档似乎暗示您可以使用

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

也从 phpDocumentor manual :

@用法与@see非常相似,请参见有关@see的详细信息,请参阅格式和结构。@使用标签与@see有两种不同之处。“看是” 单向链接,意思是包含@see标记的文档包含指向其他人的链接文档。@使用标签自动创建虚拟 @由其他文档中的标记使用链接到文档包含@uses标记。在其他文字,就像@see,除了自动添加返回链接。