which pattern should i adopt to comment my php code?

i just finished Coding my PHP application now the codi开发者_StackOverflowng has become somewhat Huge and and the comments i am using is looking Ugly and Ineffective, as every single line of code i have commented with // , this is my first coding and i am totally unaware of the methodology to adopt to make my comments look nicer and cleaner for the future reference to me or anyone. i would appreciate if someone suggest me the pattern with example..

Here is the function i wrote with the ugly comments i used. which pattern would you use for commenting the code?

//function to check if the uploaded Image is valid
    function valid_image($image, $target, $url, $width, $height = 0) {
            //Check if the uploaded image is of type jpeg
            //if not then pop up a warning message and return false and redirect back
        if( $image["type"] !== "image/jpeg") {
            alert('File must be of type image/jpeg'); 
            redirect_url($url);           
            return false;
            }
            //Check the file Dimension of the Uploaded Image if it matches with the defined Value
             //Get the Dimensions of the image
            list($image_width, $image_height) = getimagesize($image['tmp_name']);
            //If the Parameter Height is empty then just check the image width and ignore the height rule
            //Print the appropriate message and return false and redirect back
        if( $height == '0') {
        if( $image_width !== $width) {
            alert("Incorrect File Dimension for  " . $image['name'] . " Please make sure it is $width in width");
            redirect_url($url);
            return false;
            }
            }
            //If the function has got all the parameter then check both the defined height and width 
            //Print the appropriate message and return false and redirect back
    else if($image_width !== $width || $image_height !== $height) {
            alert("Incorrect File Dimension for  " . $image['name'] . " Please make sure it is  $width X $height  ");
            redirect_url($url);
            return false;
            }
            return true;
            }

Thanks in Advance.

Consider commenting your code with documentation in mind: Program documentation can be auto-generated from source code comments, which is very useful and will become an issue sooner or later.

I think it's safe to say that phpDocumentor's notation has reached the status of PHP industry standard. Their tutorial gives a good rundown on how it works. Here is a complete sample PHP file with phpDoc style comments. In short, the documentation standard is to precede every file, class, and method with "docBlocks":

/**  
 * This is a description of my function
 * @param string this is a description of the first parameter
 * @param int this is a description of the second parameter
 * @return int this describes what the function returns
 */ 

 function myfunc ($param1, $param2)
  { ...  }

phpDocumentor has a number of predefined @keyword keywords: @license, @version, @deprecated and many, many more.

many PHP IDEs recognize this kind of notation, and are able to extract lookup information from it that comes up when you type.

A keyword that many IDEs use to compile task lists is @todo.

One area that phpDoc and consorts do not set rules on is "inline comments" like the ones you have in between specific steps.

There are no binding rules here as far as I'm aware of; however, over the years and especially since I've joined SO, I've become less and less zealous in commenting every single step of what my code does, adopting a philosophy of "good code should comment itself".

That means limiting comments on things that are not already obvious from the code, and the names of the variables used. (Good choices in variable names are extremely important, more important than verbose commenting!)

This does not exactly answer your question, but only include comments that explain why you are doing something in a certain way. Your code should be self-explanatory by using meaningful variable and function names.

Lets have a look at

//Check if the uploaded image is of type jpeg
//if not then pop up a warning message and return false and redirect back
if( $image["type"] !== "image/jpeg") {
    alert('File must be of type image/jpeg'); 
    redirect_url($url);           
    return false;
}

You don't even need the comment here. It is clear that you check the type of the image and then display some kind of error message. image, type, jpeg, redirect and return false even occur in the code.

This way, you remove unnecessary comments and your code will look nicer.

Also consider to change you function name valid_image is not expressive. Your comment explains that the function checks whether an image is valid. Why not name the function isImageValid? This is self-explanatory, no comment needed.

Of course you might want add comments to functions to auto-generate documentation which is fine. But only use comments where it is really necessary and try to write expressive code.

Btw another way to write comments would be /*...*/.

A big thing is to keep your comments concise. For example:

//If the function has got all the parameter then check both the defined height and width 
//Print the appropriate message and return false and redirect back

Could be:

//IF ALL PARAMS ARE PRESENT, VERIFY DIMENSIONS

//Check if the uploaded image is of type jpeg
//if not then pop up a warning message and return false and redirect back

Could be:

//JPEG IMG?

Also avoid commenting on fairly self-explanatory stuff. Comments like:

//if not then pop up a warning message and return false and redirect back

...shouldn't be necessary. They will make it harder to keep track of useful comments, and the code itself.

Line breaks between related blocks of code can also help clarify things a lot.

You'll want to code in such a way that comments are superfluous.

I would refactor this code to reduce the need for comments. I would create new methods, like isJpeg(), and I would remove the redirecting from the function and instead use something like redirectUnless(valid_image()).

A statement like the following requires no comments as anyone can understand what that does.

if ($image->isJpeg())

I'd further recommend reading Clean Code.

Indenting it does a fair amount of good:

//function to check if the uploaded Image is valid
function valid_image($image, $target, $url, $width, $height = 0) {
    //Check if the uploaded image is of type jpeg
    //if not then pop up a warning message and return false and redirect back
    if( $image["type"] !== "image/jpeg") {
        alert('File must be of type image/jpeg'); 
        redirect_url($url);           
        return false;
    }
    //Check the file Dimension of the Uploaded Image if it matches with the defined Value
    //Get the Dimensions of the image
    list($image_width, $image_height) = getimagesize($image['tmp_name']);
    //If the Parameter Height is empty then just check the image width and ignore the height rule
    //Print the appropriate message and return false and redirect back
    if( $height == '0' && $image_width !== $width) {
        alert("Incorrect File Dimension for  " . $image['name'] . " Please make sure it is $width in width");
        redirect_url($url);
        return false;
    }
    //If the function has got all the parameter then check both the defined height and width 
    //Print the appropriate message and return false and redirect back
    else if($image_width !== $width || $image_height !== $height) {
        alert("Incorrect File Dimension for  " . $image['name'] . " Please make sure it is  $width X $height  ");
        redirect_url($url);
        return false;
    }
    return true;
}

I would take a look at PhpDocumenter This is a tool to create HTML documentation of your code.

Here is a beginner tutorial on how to document you code:

http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.starting

I really really prefer to have /* ... */ comments surrounding any function header or class header comments.

inline code comments of // are easy, but so are # comments. In my editor, they show as various colors based on what comment type I am using (jEdit) I use this to my advantage.

Also, simply as to the style of your comments... I would highly suggest making the function header comment more descriptive. For instance, the function header should tell you about the invalid jpeg checks you are doing inside the code, rather than having to read down and find out that invalid jpegs are going to throw an error - It should say that in the comment header block.