Мне нужно прокомментировать огромное количество информации только в нескольких файлах, и когда я смотрю вокруг Google и здесь, в SO, я продолжаю находить результаты, соответствующие 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?
?>
Знание правильного стиля важно. Это помогает другим людям понять, как работает ваш код, и как его использовать в будущем, если вы этого не объясняете.
В общем, PHP, похоже, имеет множество разных руководств по стилям...
Но в целом, что-то, что нужно запомнить о комментировании, - это... вы, вероятно, не хотите комментировать каждую строку в своем коде. Вместо этого попробуйте сделать свой код доступным для чтения 1 (как есть). И комментарий (в основном), когда вам действительно нужен кто-то другой, чтобы понять, что делает ваш код.
1http://www.codinghorror.com/blog/2008/07/coding-without-comments.html
Взято из 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
PHP Комментарий больше фристайла, чем вы думаете. Тем не менее, причина, по которой действительно конкретные стандарты комментариев становятся важными, связана с тем, как они взаимодействуют с определенной средой IDE для ускорения разработки. В этом случае вы сможете посмотреть, как IDE хочет, чтобы вы комментировали.
Важно отметить, что функции @param и что они @возвращают
Вы можете увидеть хорошую информацию о правильном комментировании в этом вопросе о переполнении стека и ответить: Каков надлежащий формат документации по функциям PHP?