PHP：评论标准
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/9067094/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
PHP: Commenting standards
提问by Brian Graham
I need to comment massive amounts of information in only a handful of files, and when I look around Google and here at SO, I continue to find results matching coding standards, when I need commenting standards. My coding matches most coding standards except not when it comes to commenting.
我只需要在少数几个文件中评论大量信息，当我环顾 Google 和 SOcoding standards时，当我需要评论标准时，我会继续找到匹配的结果。我的编码符合大多数编码标准，但在评论方面则不然。
Could someone please provide examples for the following?
有人可以提供以下示例吗？
<?
// 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?
?>
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.
了解正确的风格很重要。它可以帮助其他人了解您的代码是如何工作的，以及如果您不在场解释它，将来如何使用它。
回答by summea
In general, PHP seems to have a lot of different style guides...
一般来说，PHP 似乎有很多不同的风格指南......
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 readable1(as is.) And comment (mostly,) when you really need someone else to understand what your code is doing.
但总的来说，关于注释的一些事情要记住……您可能不想对代码中的每一行都进行注释。相反，尝试使您的代码可读1（按原样）。并在您确实需要其他人了解您的代码正在做什么时（主要是）进行注释。
1http://www.codinghorror.com/blog/2008/07/coding-without-comments.html
1 http://www.codinghorror.com/blog/2008/07/coding-without-comments.html
回答by David Chan
Taken from http://www.kevinwilliampang.com/2008/08/28/top-10-things-that-annoy-programmers/
摘自http://www.kevinwilliampang.com/2008/08/28/top-10-things-that-annoy-programmers/
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.
解释“如何”而不是“为什么”的评论
入门级的编程课程教会学生尽早评论并经常评论。这个想法是，评论太多总比评论太少要好。不幸的是，许多程序员似乎将此视为对每一行代码进行注释的个人挑战。这就是为什么您会经常看到类似以下代码片段的内容，该代码摘自 Jeff Atwood 在 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) }你知道这段代码是做什么的吗？我也不。问题是，虽然有很多注释描述了代码在做什么，但没有一个描述它为什么这样做。
现在，考虑使用不同注释方法的相同代码：
// square root of n with Newton-Raphson approximation r = n / 2; while ( abs( r - (n/r) ) > t ) { r = 0.5 * ( r + (n/r) ); }好多了！我们可能仍然不能完全理解这里发生了什么，但至少我们有一个起点。
注释应该帮助读者理解代码，而不是语法。一个公平的假设是，读者对 for 循环的工作原理有基本的了解；无需添加诸如“// 迭代客户列表”之类的注释。读者不会熟悉的是你的代码为什么有效以及你为什么选择按照你的方式编写它。
also... phpdoc
还有... phpdoc
回答by Kristian
PHP Commenting is more freestyle than you may think. However, the reason why really specific comment standards becomes important is because of how they interact with particular IDE's for speeding up development. In that case, you'd be able to look up how an IDE wants you to comment.
PHP Commenting 比你想象的更自由。然而，真正特定的注释标准之所以重要，是因为它们如何与特定的 IDE 交互以加快开发速度。在这种情况下，您将能够查看 IDE 希望您如何评论。
Whats important is usually marking what a functions @param's are and what it @return's
重要的是通常标记@param 的函数是什么以及它@return 是什么
You can see some good information about proper commenting in this stack overflow question and answer: What is the proper PHP function documentation format?
你可以在这个堆栈溢出问答中看到一些关于正确注释的很好的信息：什么是正确的 PHP 函数文档格式？
