So this is a basic programing tool that is too often overlooked.
I learn programing by looking at other peoples work and figuring out what each command does. Having comments in the code provides me with an idea of what the author was thinking while writing that part of the code.

Additionally, commenting your code allows the code to be modified by others for uses other than what it was originally written for. This type of versitility makes the overall value of the script higher. Many programmers believe that they should protect their scripts by intentionally making them difficult to read. This actually makes the scripts less desireable because fewer people can modify or fix such scripts.

So I'd like to take this opportunity to explain how to comment your code, when to comment your code, and what comments you should make.

PHP comments are made with a double slash // preceeding the comment.


The double slash is only good for one line of code so new double slashes are needed for each line of comment.


The double slash has yet another use. a comment can exist on the same line as the code which it describes as long as the comment comes after the PHP code.


While the double slash is the commenting method devoloped for PHP, the double slash is not the only commenting tag that PHP will allow.

Perl users will be happy to know that shell comment tags are welcome as are C program comment tags.

The pound sign # is used for comments in shell programs like Perl and are used the same way as the PHP double slash. The comment follows the pound sign, a pound sign is only good for one line of comment, and a comment can share the same line as code as long as the comment comes after the code.


C-style comment tags are a little different. The slash star - star slash /* */ tags require the comment to be opened with a slash star and closed with a star slash.


The slash star - star slash comment tags require a bit more work but the work pays off. The comment can span accross several lines as long as the comment is correctly opened and closed.


Additionally, the C-style comment can come before or after any code as long as the open and close tags are used properly.




Sorry, I know that that is rude.
Above please notice a block comment using a shell comment tag.

When a new section of code is started, you may want to use a bold statement like a block comment to introduce the next section. This may occur after defining all of your functions and before coding your output such as HTML.

The most common use of the block comment is at the top of the script to identify the script name, use, version, copyright info, and author info.
Example:


Comments before functions, especially complex functions, describing what the function does even if the function is pre-defined in PHP. This way if a bug pops up in the program, you can quickly identify the problem function.


Another good place for a comment is near code that you have had or are having trouble writing.
Say you know what you want the code to do but are confussed about how to write it, Add a comment in the place in your code where you are having problems. The comment should describe what you wantto accomplish and what is causing problems.
This will help keep you focused on your goal. Many times the answer is obvious once we stop looking what went wrong and start looking at what went right. Too many people simply delete the problem code and start from scratch because of frustration.
The frustration comes from loosing focus of the logic you wanted to use. Comments remind you what the plan was.
Comments also make it easier for others to help you fix problems.
Example:

Obviously, this code doesn't actually do anything.

Commenting can make a good script look great. Not only will comments help others to use your code but will make your code easier to write, fix, and modify.

Try to keep your comments on topic, jokes and personal comments just clutter the code. Sometimes the best comment is to let a piece os code speak for itself.

Remember, describe the code and what you want it to do and you'll find that your scripts will be easier to write.

Happy coding
vujsa

    [/tab]Another very good article vujsa... I'm a programmer myself and working in the field of networked/distributed apps - I've long realized the importance of comments in the right place and what it can do to even your own code. Coz, if you leave your own code untouched for a while, when you get back to it next - I particularly find myself completely lost.. Comments always have helped me get started from the right point again... One of my professors in school used to harp on and on about the importance of comments - but I never realized how important they were in reality till I came down to sitting at a terminal 24/7 and writing code..

[tab]Another small tip I'd add to this is - for the more serious coders, try putting a comment wherever you end a function/loop/class with a curly brace "}".. For example

    The advantage of inserting such ending comments won't be apparent till you actually get around to doing it. For a long series of nested loops/classes, or loops inside a function - this makes your life immensely easier when you try to read your code later on. You KNOW for a fact exactly which brace terminates which class/function/loop

Anyways, good one. Glad to have you here among us

microscopic^earthling,
Excelent tip. That may be the most important idea I've ever recived in a forum.

I can't begin to count the number of times I've left a closing bracket out and couldn't find it. Playing the open open close open open close open close close open close close game.

Sometimes you don't even get error or warning messages just nothing works.

Which leads me to a good follow up topic.
Indenting your code will help to clean your scripts up. Such indenting will provide as much information about your scripts as comments do.

Indentions help to identify command relationships and makes debugging you code easier.

Dependind on where you learn PHP an indent is either 4 or 5 spaces or a tab.
Tabs don't always show correctly in some script editors.
Standardization seems to be leaning towards 4 spaces and never tabs.

Here is an example of proper indentation:


Happy coding
vujsa

Very nice thread you started here vujsa! Another thing comments are good for is hiding code that you don't want a browser to display (perhaps because you don't need that code anymore or you're troubleshooting). This is called commenting out the code. I plan to do this to my webpages (whenever I get a new password PM'ed to me so that I can access cPanel for the first time, lol). Nice work, vujsa!

I think you will soon be in my list of Special members at Asta along with MC, M^E and NiLsC..

Agree with Opaque there.. I see him heading towards that soon Keep up the good work vujsa...

Avery good tutorial. I have to second the rest of the posters here. You have quality posts and took the time to put it down for the rest of the community.

Another +1 reputation point for you.

Nils

I just wanted to link to my other article as it closely related.

Good Comments Make Good HTML!

Here you'll find tips for commenting your HTML and JavaScript.

Happy coding,
vujsa

Thanks you vujsa for the tips you gave us about the need to comment our php code. I agree that it has invaluable importance for any programmer but mainly for the beginners, because we need to develop good code habits early. Good, let's put it into practice right now!

Thank you! like the


on lol !!

This post has been edited by vmkrightpoint: Feb 15 2008, 07:09 AM