Мне нужно комментировать огромное количество информации только в нескольких файлах, и когда я смотрю вокруг 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?
?>
Важно знать правильный стиль. Это помогает другим людям понять, как работает ваш код и как его использовать в будущем, если вас там нет, чтобы объяснить это.