PHP注释规范

Question

我需要在仅有的几个文件中对大量信息进行注释，在谷歌和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?

?>

了解正确的编程风格非常重要。它可以帮助其他人理解您的代码运作方式，并在没有您解释的情况下，如何在未来使用它。

- Nahydrin

---

phpDocumentor: http://www.phpdoc.org/ 具体来说，请注意教程中使用的约定。 - Michael Berkowski

@Michael，我不被允许使用那个工具。 - Nahydrin

即使您无法使用该工具，遵循其注释约定也是有用的。 - Michael Berkowski

你不一定要使用这个工具，但它们提供了一种相当标准的记录代码的方式。该工具只是将所有文档编译到一个区域供他人使用。 - WWW

即使您不生成文档，PHPDoc注释也会被许多开发IDE解释并显示为代码提示。而且它熟悉易读，其他开发人员也容易编辑。 - DerVO

Answer 1

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

1. phpDocumentor风格
2. Zend Framework风格
3. Pear风格

但是总的来说，有一件事要记住关于注释...你可能不想在代码每行都写注释。相反，尽量让你的代码易读（就像这样）。当你真正需要其他人理解你的代码时再增加注释。

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

- summea

---

我可以使用Zend框架的样式，而且非常容易遵循。谢谢！ - Nahydrin

FYI，Zend的链接已经失效了。找不到替代链接（这就是我来到这里的原因）。 - James

@James 谢谢你告诉我，我已经更新了链接。 - summea

请注意，所有 Zend 文档块都使用 phpDocumentor 格式。 - Geoffrey Hale

Answer 2

来源于http://www.kevinwilliampang.com/2008/08/28/top-10-things-that-annoy-programmers/

程序员最讨厌的十件事

1. 抄袭他们的代码
2. 拖延时间
3. 不写注释
4. 不测试你的代码
5. 在非常短的时间内要求完成一项任务
6. 不给足够的资源和支持
7. 不了解业务需求
8. 频繁地改变需求
9. 忽略了性能问题
10. 不尊重他们的工作

Comments that explain the “how” but not the “why”

Introductory-level programming courses teach students to comment early and comment often. The idea is that it’s better to have too many comments than to have too few. Unfortunately, many programmers seem to take this as a personal challenge to comment every single line of code. This is why you will often see something like this code snippit taken from Jeff Atwood’s post on Coding Without Comments:

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)
}

Do you have any idea what this code does? Me neither. The problem is that while there are plenty of comments describing what the code is doing, there are none describing why it’s doing it.

Now, consider the same code with a different commenting methodology:

// square root of n with Newton-Raphson approximation
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
    r = 0.5 * ( r + (n/r) );
}

Much better! We still might not understand exactly what’s going on here, but at least we have a starting point.

Comments are supposed to help the reader understand the code, not the syntax. It’s a fair assumption that the reader has a basic understanding of how a for loop works; there’s no need to add comments such as “// iterate over a list of customers”. What the reader is not going to be familiar with is why your code works and why you chose to write it the way you did.

also... phpdoc

- David Chan

Answer 3

PHP的注释比你想象的更加自由。然而，特定的注释标准之所以变得重要，是因为它们与特定的IDE交互以加快开发速度。在这种情况下，您可以查看IDE希望您如何进行注释。

重要的是通常标记函数的@param和@return

您可以在此堆栈溢出问题和答案中查看有关适当注释的一些好信息：什么是适当的PHP函数文档格式？

- Kristian