Commenting code in PHP while using a framework

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.

---

Not related to visual style of the comments, but a comment like "Check if variable_name is greater than zero" is a bad comment in and by itself. All it does is duplicate the information on the line below. The code should contain names on variables, functions and other things that can be read to know what's going on.

Other than that, I see nothing wrong with the double-slash-comment types.

---

// Check if variable_name is greater than zero

Such comments are worthless. I only know little PHP, and even if I didn't knew anything about it, I could immediately tell (or at least, very confidently guess) that after looking at the line.

As a general (language-agnostic) rule of thumb, write code that is mostly self-documenting (by using descriptive names, avoiding non-obvious shortcuts, etc.) and only comment why you do something which looks wrong/strange.

---

Personally, I document inline sparingly (I do religiously put doc-blocks in for methods, classes and member variables though). I believe that code itself should be as self documenting as possible.

There will be times where you need to do something non-obvious or possibly even counter-intuitive. That's the time for inline comments. Try to explain not what the block of code does, but why it does it that way.

There's a great example in Phing's CodeCoverageReportTask class:

// Strange PHP5 reflection bug,
//     classes without parent class or implemented interfaces
//     seem to start one line off
if ($reflection->getParentClass() == NULL
    && count($reflection->getInterfaces()) == 0)
{
    unset($coverageInformation[$classStartLine + 1]);
}
else
{
    unset($coverageInformation[$classStartLine]);
}

And another good one just a few lines down from that:

// PHP5 reflection considers methods of a parent class to be part
//     of a subclass, we don't
if ($method->getDeclaringClass()->getName() != $reflection->getName())
{
    continue;
}

---

I completely agree that comments should never explain what the code does, only why. But, it is definitely good practice to put necessary comments into the code. When I go back and look over some of my code (PHP or other), I wish I had commented more clearly.

But, the only standard with comments is consistency! Be consistent and you don't have to worry so much about confusing comments (only about when to use them).

---

Some (if not most) PHP programmers use the double-slash method (//) for commenting their code. There really is no standard, and I've seen people who comment using the pound symbol (#) at the beginning of a line, and others who comment out blocks with /* and */.

---

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.