What is the preferred way of notating methods in comments?

Sometimes one has to refer to another method when commenting. Here some example in PHP:

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

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

So what if there would be a non-static method bar in class B ? What is the best way to name other methods in comments?

Edit

The PHP manual seems to use mysqli->affected_rows as well as PDO::beginTransaction . But what it does not is including the parentheses after the method's name. What is pro and con here? I mean it is quite obvious that a method is followed by parentheses, so why no leave 'em out?

Thx in advance!

---

You could use the -> operator to reference an instance/object method rather than a class method. PHP.net does that in their manual as well (see MySQLi class for example).

---

I would write:

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

My most strongly held opinion concerning my various changes is that letterbox comments are the work of the Devil. Regarding your static vs. non-static thing, I understand and use B::bar() to refer to the function definition for conversational purposes, whether or not bar() is static.

The above example is, of course, for illustrative purposes only, because if there were actually a function A::foo() that did nothing but call B::bar() , I would not include the comment, because if the person reading my code is an idiot, I do not wish to help him.

---

In my opinion, your example is sufficient. You should refer to B::bar as B::bar(), though.

You might want to consider using the @uses php-doc tag, which will automatically create a @usedby reference in documentation generated for B::bar(), pointing back to class A.

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

As far as documentation is concerned, the method being static is not relevant to @uses, @usedby or @see, only @static. The static notation in the @uses tag simply communicates the scope to look for the bar() method in, not to denote @static.

链接地址: http://www.djcxy.com/p/14938.html

上一篇: 你的方式来写简单的评论

下一篇: 注释中注释方法的首选方式是什么？