Jump to content

Standard sytax for commenting your code?


maexus

Recommended Posts

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?

Link to comment
Share on other sites

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

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

@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)
{
    
}
?>

Link to comment
Share on other sites

 

 

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.

 

 

Link to comment
Share on other sites

 

 

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 ?

 

Link to comment
Share on other sites

  • 1 month later...

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?

Link to comment
Share on other sites

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

Link to comment
Share on other sites

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.

 

 

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

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
}

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

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.

Link to comment
Share on other sites

  • 2 weeks later...

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

Link to comment
Share on other sites

This thread is more than a year old. Please don't revive it unless you have something important to add.

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Restore formatting

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...

Important Information

We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.