Home > Programming, php > php: Whats your commenting style?

php: Whats your commenting style?

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

Categories: Programming, php Tags:
  1. April 11th, 2012 at 20:29 | #1

    I am love this blog very much, i will continue to readcheap ray bans

  2. April 11th, 2012 at 20:33 | #2

    It was very informative.designer clothes cheap I appreciate your effort to put this piece together.fashion clothesthank you for your share.

  3. April 16th, 2012 at 19:46 | #3

    I was never one to patiently pick up broken fragments,and new.What is broken–and I`d rather remember it as it was at its best than mend it and see the broken places as long as I lived.–Rhett

  4. April 20th, 2012 at 02:51 | #4

    e to patiently pick up broken fragments,and new.What is broken–and I`d rather remember it as i

  5. April 20th, 2012 at 02:52 | #5

    e to patiently pick up brWhat is broken–and I`d rather remember it as i

  6. April 20th, 2012 at 02:52 | #6

    er remember it as it was at its best than mend it and see the broken places as long a

  7. April 20th, 2012 at 02:52 | #7

    ck up broken fragments,and new.What is broken–and I`d rather remember it as i

  8. April 25th, 2012 at 04:36 | #8

    What is love?
    Is a wonderful addition: a miss with a miss, 15 will be able to become the moon.
    Are an extraordinary hearing: Even across the mountains, but also exciting to hear each other’s heartbeat.

  9. May 2nd, 2012 at 21:20 | #9

    I like you to provide useful information in your article. I will bookmark your blog and periodically thereafter to share your happiness. I am sure to be here and learn many new things! I wish you get better and better.

  10. May 2nd, 2012 at 23:07 | #10

    I really enjoyed this site. This is such a Great resource that you are providing and you give it away for free. It gives in depth information. Thanks for this valuable information.

  11. May 3rd, 2012 at 02:12 | #11

    I agree with one of the other posters – you write very well indeed.

  12. May 4th, 2012 at 04:55 | #12

    Thanks for sharing such a nice post
    regards…

  13. tommy1222
    May 4th, 2012 at 07:43 | #13

    I am hunting this post and thinking of it’s theme and attempting to know what is this post concerning. vigrx plus

  14. May 5th, 2012 at 03:35 | #14

    Men, instead of being content with being freely given for long periods what they hardly dared hope to get once, are forever asking their mistresses for an account of the present, the past and even the future. As they get used to a mistress, they try to dominate her, and they become all the more demanding the more they are given.

  15. May 8th, 2012 at 01:23 | #15

    a style similar towards the brides??�even down towards the miniature train! Most types are readily available in white which make them excellent for First Holy Communion. If you??�

  16. May 11th, 2012 at 00:45 | #16

    This is a very good article, has its own style and features an excellent article, make myself more upscale, more trendy, this is an excellent article, so you have a stylish and upscale image, which isa perfect decision to make themselves more upscale and stylish, do not miss this good opportunity, this is a perfect decision, good performance, first-class way.

  17. May 12th, 2012 at 06:54 | #17

    報告によると、小沢氏は1980年の彼の政治的ピークの桃の嵐の中で取得します。当時、政界、レッズ、自民党与党の副社長金丸手紙の後継、唯一40代であった​​。彼は頻繁に高級ホテルで、政治的·アベニューティンバーランド レディース 、永田町パーティのレストランを頻繁に。それは女性アンカー池田直美と不倫と噂されたときに高い乗車中。池田妊娠小沢肉と血がティンバーランド アウトレット、政治的圧力に起因するが、密かに子供たちが出産したことを報告した。レポートには、小沢氏が愛のキラーでより多くの背後にある駆動力を”シーンの背後にある一般的な”非日本の政治として知られていることを明らかにした。小沢氏は肉と血を所有したいmbt shoes australia 、と池田の子が破壊説得するように秘書に送信されません。その後、子どもたちは、生物学的母親を残してできるようにするためにメーターに再適用していた、政治家としてのキャリア外スキャンダルの深い恐怖、子供が生まれていることを通知した。二歳、子供は小沢古い採択に移した。彼のシールは、武術の非嫡出子の機密性はmbt shoes clearance 、非これまでのところ、よくやったけど、密かに子供の池田露風ではなく、彼らの子供レストラン女将を高めるために、彼のハードワークのための単語を出産した。

  18. May 12th, 2012 at 06:55 | #18

    Match of North Face Men’s Windstopper different materials mixed with great layering top!

  19. May 14th, 2012 at 22:36 | #19

    Where, O death, is your victory? Where, O death, is your sting? The stin g of death is sin, and. The power of sin is the law. But thanks be to Go d, who gives us the victory through our Lord Jesus Christ.

  20. May 17th, 2012 at 04:41 | #20

    Who will separate us from the love of Christ? Will hardship, or distress , or persecution, or famine, or nakedness, or peril, or sword? No, in al l these things we are more than conquerors through him who loved us.

  21. May 17th, 2012 at 10:56 | #21

    Great article,it so fun.jackzluck Monster Beats Outlet

Comment pages
1 2 3 144
  1. October 10th, 2009 at 03:41 | #1