PHP:评论标准

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似乎有很多不同的风格指南......

1. phpDocumentor风格
2. Zend框架风格
3. 梨的风格

但总的来说,记住评论的一些事情是......你可能不想评论代码中的每一行.相反,尝试使您的代码可读¹(按原样).并且当您真正需要其他人了解您的代码正在做什么时(主要是).

¹ 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