Commenting code in PHP while using a framework

Question

I'm creating a simple application using the Kohana PHP framework, just FYI. This is my first time with the framework.

While developing classes or functions I'm commenting my code using DocBlock. How should I comment my code while using the 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 a standard for inserting comments in the code?

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.

Answer 1

Comments are liars!

The problem with comments 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 document 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.