Question

我需要在少量文件中评论大量信息，当我环顾谷歌并在此处时，我仍需要找到符合coding standards的结果，当我需要评论标准时。我的编码符合大多数编码标准，但不是评论时。

有人可以提供以下示例吗？

<?

    // beginning of file comments

    require( 'filename.php' ); // require or include, with filename

    public class Test { } // class without constructor

    public class Test // class with constructor, if different from above
    {
        public function __constructor() { } // constructor, no parameters

        public function __constructor(var1, var2) { } constructor, with parameters

        public function func1() { } // function, no parameters

        public function func2($var1, $var2) { } // function, with parameters

        public function func3( $optional = '' ) { } // function, optional parameters

        private function func4() { } // private function, if different from above

        public static staticfunc1() { } // public static function, if different from above

        public function returnfunc1(var1, var2) // function, with return value
        {
            return var1 + var2; // return statement, dynamic
        }

        public function returnfunc2() // function, with unchanging return value, if different from above
        {
            return 1; // return statement, unchanging, if different from above
        }

        public function fullfunc1() // declaration, calling and assignment, in function
        {
            $var1; // variable declaration

            $arr1 = array(); // array declaration, if different from above

            $var2 = dirname( __FILE__ ) . '/file.ext'; // variable assignment

            $this->var1 = $path . '_'; // class variable assignment

            ob_start(); // function call

            $this->func1(); // class function call

            ob_end_clean();

            foreach($arr as $key => $val) { } // foreach and for loops
        }

        public $var1; // public variable

        private $var2; // private variable, if different from above
    }

    // ending of file comments?

?>

了解合适的风格很重要。它可以帮助其他人了解您的代码如何工作，以及如果您不在那里解释它将来如何使用它。

Answer 1

一般来说，PHP似乎有很多不同的风格指南......

phpDocumentor style
Zend Framework style
Pear style

但总的来说，记住评论的一些事情是......你可能不想评论代码中的每一行。相反，尝试使您的代码可读¹（按原样）。当您真正需要其他人了解您的代码正在执行的操作时，（主要是）评论。

¹ http://www.codinghorror.com/blog/2008/07/coding-without-comments.html

Answer 2

取自http://www.kevinwilliampang.com/2008/08/28/top-10-things-that-annoy-programmers/

解释“如何”而不是“为什么”
的评论
入门级编程课程教会学生尽早发表评论   经常评论。这个想法是，拥有太多的东西会更好   评论比太少了。不幸的是，许多程序员似乎   把这作为个人挑战来评论每一行   码。这就是为什么你经常会看到像这个代码snippit的东西   取自杰夫阿特伍德关于没有评论的编码的帖子：
r = n / 2; // Set r to n divided by 2
// Loop while r - (n/r) is greater than t
while ( abs( r - (n/r) ) > t ) {
    r = 0.5 * ( r + (n/r) ); // Set r to half of r + (n/r)
}
你知道这段代码的作用吗？我也不。问题是   尽管有很多评论描述了代码是什么   做，没有人描述它为什么要这样做。

现在，请考虑使用不同评论方法的相同代码：
// square root of n with Newton-Raphson approximation
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
    r = 0.5 * ( r + (n/r) );
}
好多了！我们仍然可能无法准确理解发生了什么   在这里，但至少我们有一个起点。

评论应该有助于读者理解代码，而不是   句法。这是一个公平的假设，读者有一个基本的   理解for循环如何工作;没有必要添加评论   例如“//遍历客户列表”。读者不是什么   熟悉的是为什么你的代码有效以及你选择的原因   按照你的方式写下它。

...也 phpdoc

Answer 3

PHP评论比你想象的更自由。但是，真正具体的评论标准变得重要的原因在于它们如何与特定的IDE进行交互以加速开发。在这种情况下，您将能够查找IDE希望您发表评论的方式。

重要的是通常标记@param的函数是什么以及它返回的是什么

您可以在此堆栈溢出问题和答案中看到有关正确评论的一些有用信息：What is the proper PHP function documentation format?

PHP：评论标准

3 个答案:

解释“如何”而不是“为什么”