Standard sytax for commenting your code?

[maexus]

Now, until recently, I rarely commented my code. I've since changed that after digging up stuff from 3-4 years ago that has no comments and some of it is just hard to follow. I have two questions for everyone.

 

1) Do you comment for yourself, for someone who would be fairly experienced in php or the lowest common denominator who might read your code? How thorough are you?

 

2) Is there a standard syntax/format that you follow for commenting functions, classes, variables?

[keeB]

Only write useful comments

 

Not useful

<?php
public function doLoop() {
   //does a loop
}
?>

 

Useful

 

<?php

function doLoop($p1, $p2) {
/**
    * @p1 <type expected>: function
    * @p2 <type expected>: function
    *
    * Description ...............
    */
}
?>

[maexus]

I've seen comments using @ before. What is the specific meaning behind the @ in your comment block? Is it part of a larger comment standard you are using?

[keeB]

http://www.phpdoc.org/

[Liquid Fire]

does php doc parse those types of comment inside the code?  I alway put my php doc type comment before the function of class or whatever.

[sequalit]

i was wondering how to document your functions like that with PHP. Thanks

[Catfish]

I usually have an area at a fixed number of columns across my page which is for commenting on the code in that row specifically, then I will also use comments at the start of code blocks to state the overall process of that block of code, then additional comments throughout the code block to comment on what each area is doing specifically. I think I go a little overboard with my commenting but it's what they expected when I did some programming classes through a uni so I guess it stuck.

 

I also like to set different syntax highlight colours for different comment styles like:

/* grey */

# yellow

// lime green

 

and I usually use /* */ for larger descriptions about the entire file (at top of file)

# for end-of-line commenting

and // for comments that I want people to notice.

 

Of course that requires other users to have the same syntax highlighting as me but I'm only hobby programmer so it's only my cousin that will see it.

 

 

I think the general rules for comments are so long as you:

1. make the comments descriptive and relevant to the code and

2. the comments are consistently spaced/tabbed out throughout the file to maximize readability.

 

 

I didn't know about phpdocu. Will have to look at that one day.

[Daniel0]

@keeB: The docblock must be outside the function, not inside. You usually also put the description before the @whatever things (I'm not sure what they're called).

 

It would look something like this:

<?php
/**
* This function does a loop.
*
* @param integer $p1 bla bla
* @param SomeClass $p2
*/
function doLoop($p1, $p2)
{
    
}
?>

[keeB]

Yeah, I noticed that at the end. I'm used to it in python.

[Xeoncross]

 

 

I use a mix of NaturlDocs and PHPDoc for my Code. Functions look like this:

 

<?php
/*
   Function: Multiply

   Multiplies two integers.

   Parameters:
      x - The first integer.
      y - The second integer.

   Returns:
      The two integers multiplied together.

   See Also:
      <Divide>
*/
int Multiply (int x, int y) {  return x * y;  };

?>

 

I use http://naturaldocs.org/documenting/reference.html as I think it is a LOT easier to read than

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html

 

And then at the top of the file I do this:

/**
* Framework NAME
*
* ABSTRACT
*
* Tell us about this file
* 
* @package    file_name.php
* @version    1.0.0 <4/5/2008>
* @author     Name <name@site.com>
* @copyright  Copyright (c) 2008 You <http://www.site.com>
* @license    http://www.gnu.org/licenses/gpl-3.0.html General Public License (v3)
*/

 

Like what ZEND does.

 

 

[Gurzi]

 

 

I use a mix of NaturlDocs and PHPDoc for my Code. Functions look like this:

 

<?php
/*
   Function: Multiply

   Multiplies two integers.

   Parameters:
      x - The first integer.
      y - The second integer.

   Returns:
      The two integers multiplied together.

   See Also:
      <Divide>
*/
int Multiply (int x, int y) {  return x * y;  };

?>

 

I use http://naturaldocs.org/documenting/reference.html as I think it is a LOT easier to read than

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html

 

And then at the top of the file I do this:

/**
* Framework NAME
*
* ABSTRACT
*
* Tell us about this file
* 
* @package    file_name.php
* @version    1.0.0 <4/5/2008>
* @author     Name <name@site.com>
* @copyright  Copyright (c) 2008 You <http://www.site.com>
* @license    http://www.gnu.org/licenses/gpl-3.0.html General Public License (v3)
*/

 

Like what ZEND does.

 

 

 

Does it possible to modify Eclipse PHP to recognise NaturalDoc ?

 

[Xeoncross]

I don't know, I have never used "Eclipse". But now that I got Xdebug under my belt - I just might start on it.

[maexus]

Thanks for the responses, I just like to adhere to a standard if there is one out there.

[Rebelrebellious]

I am pretty new to programming, but I have been making announcement functions in my programs that output debug messages to screen, log files, wherever. (I also include a means of enabling or disabling the output.) As a result, aside from section headings I have been announcing my line by line comments. This helps me at runtime when debugging and it serves double as in-code commenting.

 

I am curious what anyone reading this thinks about my strategy. Is there a negative consequence to such a strategy? Is this common?

[Xeoncross]

I am curious what anyone reading this thinks about my strategy. Is there a negative consequence to such a strategy? Is this common?

 

Make an error handler that will do it for you. That way you can trigger errors wherever you need to know what is going one without having to build your own solution.

 

<?php
trigger_error('This is an warning', E_USER_WARNING);
trigger_error('This is an notice', E_USER_NOTICE);
trigger_error('This is an error', E_USER_ERROR);
?>

 

Read up on http://us2.php.net/set_error_handler

[Rebelrebellious]

Thanks for the heads up. That does seem like an ideal approach.

 

------------------------------------------------------------------

 

Is there any way for a script to read its own comments that are written with // or /* */ ?

 

Would it need to be done with file_get_contents($SERVER['PHP_SELF']) ?

If so, I imagine the comment would need to self identify the subject of the comment.

This is probably not the best way of doing things.

I was just thinking about the possibility of doing something like:

 

              trigger_error(get_correct_comments(), E_USER_NOTICE);  or maybe: get_last_comment()

 

Even as I tpye this, I am thinking that the usefullness of such a function would be limited once the program was near completion. But it doesn't hurt to ask.

 

 

[Daniel0]

The reflection classes can read DocBlock style comments.

 

http://php.net/reflection

[Rebelrebellious]

Holy buckets! I will need to read about reflection again later. There is a lot of potential there. Too much for me to worry about today.

Thanks again.

[deadonarrival]

Docblocks for every class/function

 

Basically package/version/copyright for everything, a brief description, and on functions the arguments and returns.

 

Also I put a lot of //comments in my code, as a description to whoever's reading it.

 

The docblocks help advanced users and for documenting, and are useful when in your IDE if it shows the docblock on function calls (can see what arguments I need a lot easier)... the inline comments are for anyone wanting to learn from/understand/change my code, rather than just use it. They describe anything non-straightforward.

 

Eg I don't do

//print name

print $username;

but anything more complex, or a quick description of what's going on, gets put in.

 

Finally

/** **/ docblocks for those using the interface of the function/class

// and /* */ inline comments of what's going on

# for "working" comments. These are the comments for me when I leave/come back to a function, just to tell me what needs to be done. A "todo" so to speak. Eg when I close the package I leave one where I'm up to, with what I'm doing. And if I want to change/optimise anything it gets one. These are always gone by the beta, since I'll have dealt with them before then.

[bholbrook]

Make an error handler that will do it for you. That way you can trigger errors wherever you need to know what is going one without having to build your own solution.

 

You can also use a try/catch block to get the information you need without forcing an error... http://ca.php.net/try

 

try
{
    throw new Exception("This is a message to display");
}
catch( Exception $e )
{
    echo $e->getMessage(); // This is a message to display
    echo $e->getLine();    // 3
}

[Rebelrebellious]

I have seen those arrows in other places, but I don't know what to call them. What are they used for? What do they mean? I don't really need an explaination, just a name or a resource where I can educate myself would be great.

 

The arrows I am referring to look like this ->

 

As per the example.

echo $e->getMessage()

 

Also, is throw new Exception pseudo code?

Sorry, and thanks.

[deadonarrival]

the -> is to get a method/property of an object $e - in this case the exception you threw.

 

It's part of the OOP (object oriented programming) idea. - the easiest way to think of the access is that it's the equivalent of $e['getmessage'] for an array, but you can call functions or variables from it.

 

Google PHP OOP, or take a peek in the OOP section of this site, for more info - it's a very big topic, but definately something worth educating yourself in.

[keeB]

I am pretty new to programming, but I have been making announcement functions in my programs that output debug messages to screen, log files, wherever. (I also include a means of enabling or disabling the output.) As a result, aside from section headings I have been announcing my line by line comments. This helps me at runtime when debugging and it serves double as in-code commenting.

 

I am curious what anyone reading this thinks about my strategy. Is there a negative consequence to such a strategy? Is this common?

 

This is what most new programmers do.

 

As you mature, you'll start to rely on a good debugger which is like 'printing to screen' but without code bloat