2

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.

Improve this question
2
  • 7
    if "check if variable_name is greater than zero" is a real example of a comment, you are definitely doing it wrong. Commented Aug 11, 2010 at 19:39
  • 1
    Can you make up your mind what your question is? Your original question is asking is there any standard (bit vague). You then say in an edit that you're only asking if it's good practice to comment your code... then in a comment to another answer you say I also saw different commenting methods, but I was asking about if is it correct to put that kind of comments into the code which clearly asks for kinds of comments... so what precisely do you want to know? Commented Aug 11, 2010 at 19:51

6 Answers 6

Reset to default
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.

Improve this answer
Sign up to request clarification or add additional context in comments.

Comments

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

Improve this answer

Comments

2

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;
}
Improve this answer

2 Comments

IMO comments should never explain what the code does, only why (or other things absolutely needed to understand it). Explaining what the code does is duplication of information, and should always be avoided.
@Arve Systad: I do it that way as well (well, 99.95% of the time). I do think there are some times that you may want to explain the how as well (which is why I put in in the OP). But your rationale is better. I'ved edited that sentiment out of my answer...
2

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

Improve this answer

Comments

1

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 */.

Improve this answer

1 Comment

Thanks for the comment. I also saw different commenting methods, but I was asking about if is it correct to put that kind of comments into the code :)
0

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.

Improve this answer

1 Comment

The video link is broken: "Not Found. The requested URL was not found on this server."

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.