PHP: Commenting code.

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

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

Answer 2

// 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 nonobvious shortcuts, etc) and only comment why you do something which looks wrong/strange.

Answer 3

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.

Answer 4

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;
}

Answer 5

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

Answer 6

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).