which pattern should i adopt to comment my php code?

Question

i just finished Coding my PHP application now the coding 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.

Answer 1

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