PHP：评论代码

Question

Good Day All,

Got theoretical question.

I'm creating a simple application using KohanaPHP framework, just fyi. This is my first time with framework and have one - maybe stupid for some of you - question.

While developing classes or functions I'm commeting my code using DocBlock. Just wondering how should I comment my code while using framework? I meant to code some parts of the code, not whole controllers.

Basically, I'm using following methods:

// Check if variable_name is greater than zero
if($this->var > 0) {
    // do something
} else {
    // do something
}

if( $result ) {
    // display confirmation message
} else {
    // display errors
}

Am I doing it right way? Is there any standard for inserting comments in the code?

Edit: Let me explain, I'm not using comments like "check if variable is greater than zero". I'm just wondering if is it good practice to put comments into the code.

Regards, Tom

Answer 1

Comments are liars! The problem with comment is that you have to update them as you update your code. If you don't, you end up with code looking like this :

// sum $a and $b
$x = $a * $a - $b;

So the best way to documente your code is to make it really clear! I would write your code like this :

if ( isPositive(3) ) {
    doA();
} else {
    doB();
}

if( $result ) {
    displayConfirmationMsg();
} else {
    displayErrors();
}

This code doesn't need comments at all because it's very simple to understand it!

Well, anyway, when I do have to write comments (almost never), I go with the // notation but I think it doesn't really matter.

By the way, check out this awesome video of uncle bob http://bit.ly/AYqFT