PHP注释标准 [英] PHP commenting standards

问题描述

我只需要评论少量文件中的大量信息，当我环顾Google以及Stack Overflow时，当我需要评论时，我会继续找到符合编码标准的结果标准.除了注释，我的编码符合大多数编码标准.

I need to comment massive amounts of information in only a handful of files, and when I look around Google and here at Stack Overflow, I continue to find results matching coding standards, when I need commenting standards. My coding matches most coding standards, except when it comes to commenting.

以下示例是什么?

<?

    // 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?

?>

了解适当的风格很重要.它可以帮助其他人了解您的代码如何工作，以及如果您不去解释它的话，将来如何使用它.

Knowing proper style is important. It helps other individuals understand how your code works, and how to use it in the future if you are not there to explain it.

推荐答案

通常，PHP似乎有很多不同的样式指南...

In general, PHP seems to have a lot of different style guides...

1. phpDocumentor样式
2. Zend Framework样式
3. 梨样式

但是，总的来说，关于注释的一些事情是……您可能不想注释代码中的每一行.相反，请尝试使您的代码可读性 ¹ (按原样.)并在确实需要其他人了解您的代码在做什么时注释(主要是).

But in general, something to remember about commenting is... you probably don't want to comment every line in your code. Instead, try to make your code readable¹ (as is.) And comment (mostly,) when you really need someone else to understand what your code is doing.

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

这篇关于PHP注释标准的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！