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