What template should I accept to comment on my PHP code?

Question

I just finished Coding my PHP application, now the coding has become a bit huge, and the comments I use look ugly and inefficient, since every single line of code that I commented with // is my first encoding and I am completely not I’m aware of which methodology to adopt so that my comments look better and cleaner for future reference to me or anyone. I would appreciate if someone would offer me a sample with an example ..

Here is the function I wrote with the ugly comments I used. which template would you use to comment 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 at Advance.

Answer 1

Consider commenting your code using documentation : software documentation can be automatically generated from source code comments, which is very useful and will become a problem sooner or later.

I think it is safe to say that phpDocumentor notation has reached the status of the industry standard PHP standard. Their tutorial gives a good description of how this works. Here is a complete sample PHP file with phpDoc style comments. In short, the documentation standard must precede each 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 several predefined keywords @keyword : @license , @version , @deprecated and many others.

many PHP-IDEs recognize this notation and can extract from it the search information that appears as you type.

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

One area in which phpDoc and spouses do not set rules is inline comments, such as the ones you have between specific steps.

There are no binding rules here, as far as I know; however, over the years, and especially since I joined SO, I have been less and less hard at commenting on every step of my code, adopting the philosophy of “good code, have to comment on yourself” .

This means limiting comments on things that are not yet obvious from the code, and the names of the variables used. (Good options in variable names are extremely important, more important than a detailed comment!)

Answer 2

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

Let's 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 do not need a comment here. It is clear that you are checking the type of image and then displaying some kind of error message. image , type , jpeg , redirect and return false even occur in code.

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

Also consider changing the function name valid_image not expressive. Your comment explains that the function validates the image. Why not name the function isImageValid ? This is self-evident, without comment.

Of course, you can add comments to the functions of automatic documentation generation, which is good. But use comments only where it is really necessary, and try to write expressive code.

---

By the way, another way to write comments is /*...*/ .

Answer 3

The main thing is that your comments are brief. For instance:

---

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

May 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 

May be:

 //JPEG IMG? 

---

Also avoid commenting on pretty obvious things. Comments like:

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

... not necessary. It will be more difficult for them to track useful comments and the code itself.

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

Answer 4

You will want to code so that comments are redundant.

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

A statement like the one below does not require comment, as anyone can understand what it does.

 if ($image->isJpeg()) 

I would also recommend reading Clear Code .

Answer 5

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

inline code comments // are simple, but # comments are. In my editor, they appear as different colors based on what type of comment I use (jEdit). I take advantage of this.

Also, just regarding the style of your comments ... I would suggest making the comment of the function header more visual. For example, the function header should tell you about invalid jpeg checks that you do inside the code, instead of reading and discovering that invalid jpegs are going to throw an error. That should say in the comment title block.

Answer 6

Indentation does this pretty well:

 //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; } 

Answer 7

I would look at PhpDocumenter. This is a tool for creating HTML documentation for your code.

Here's a beginner's tutorial on how to document code:

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