I need to comment massive amounts of information in only a handful of files, and when I look around Google and here at Stack Overflow, I continue to find results matching coding standards, when I need commenting standards. My coding matches most coding standards, except when it comes to commenting.
What would be 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) // 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? ?>
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.
Advertisement
Answer
In general, PHP seems to have a lot of different style guides…
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 http://www.codinghorror.com/blog/2008/07/coding-without-comments.html