I was writing up a few scripts and as I was adding my commenting I noticed I tend to comment differently depending on the difficulty of the script and how many different parts or procedures there are to it. I don’t have a set convention, but I suppose as with all things it would make things easier on myself and others if I had some kind of standardization…
For larger ‘areas’ that contain functions or a series of procedures that extract or parse sections of data I’m now starting with this:
/***
*
* This is a comment.
* Here I leave notes about the section and what it does.
* I may also include notes to myself here.
* Note: This could probably be done more eficiently
*
*/
As there are more breakdowns within these sections I’m using this:
/* [ Parse out the text file ] */
And further drilled down I use the more inline commenting
/* [ Print data] */
$parts = explode("|", $the_array); // get the parts
$color = false; // set color var for shading every other row
print("<table>");
// loop through data & print
foreach($parts as $key => $row){
// CSS Note: shading <tr>'s with css mostly works with nice browsers
// For IE 6+ one needs to shade the <td>'s
if($color){
print("<tr class=\"rowColor1\"> "); // start row with color 1
$color = !$color; // unset the color so it alternates next loop
} else {
print("</tr><tr class=\"rowColor2\"> "); // start row with color 2
$color = true; // set the color so it alternates next loop
}
print("<td>$row[first_name]</td></tr>"); // print cell data and close the row
}
print("</td></tr></table>");
The inline comments still seem a bit ‘messy’ to me. But for now it will work.
One of the reasons I decided to standardize is because even with commenting and extra line spaces in the scripts it was still difficult to sort out what exactly was going on. Another thing that tripped my thought was having a glance at phpDocumentor. It seems to function on how you comment your code. I did try to install it but for some reason it was way over my head. It looks like a neat tool but I rarely seem to write more than 4 different files and those are often less than 300-400 lines.
I’ve yet to test it in comments but my plugin to allow code viewing is much like bbc code. [code lang="php"] // comment [/code]
So whats your style? Is there a standard? What have you seen that looks the cleanest? Leave a comment… with some comments ;-)
Update 12/3/07 Elizabeth Naramore has written a nice article on the effectiveness of comments in your code over at the Chris Shiflett blog. It’s a great read on WHY commenting is good in your code.
php, comment, code, script, php+script, php+comment
