PHP 注释标准

Question

我需要在少数几个文件中评论大量信息，当我在 Google 和 Stack Overflow 中查看时，当我需要评论时，我会继续找到符合编码标准的结果标准。我的编码符合大多数编码标准，但涉及到注释时除外。

下面的例子是什么？

<?

    // 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) // Tunction, 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 style
2. Zend Framework style
3. Pear style

但总的来说，关于注释要记住的一点是……您可能不想注释代码中的每一行。相反，尝试使您的代码可读¹(按原样。)并在您真正需要其他人理解您的代码的作用时(主要是)发表评论。

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