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.
CODE
<?
// PHP comment goes here.
?>
// PHP comment goes here.
?>
The double slash is only good for one line of code so new double slashes are needed for each line of comment.
CODE
<?
// If one line of commenting is no enough or undesirable,
// a second line can be added this way.
?>
// If one line of commenting is no enough or undesirable,
// a second line can be added this way.
?>
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.
CODE
<?
// Let's add some valid PHP code below such as a variable assignment.
$foo = "foo_value"; // the value of $foo is "foo_value".
?>
// Let's add some valid PHP code below such as a variable assignment.
$foo = "foo_value"; // the value of $foo is "foo_value".
?>
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.
CODE
<?
# Shell-style comment tags like those used in Perl look like this.
# And the comment tag is only good for one line.
$foo = "foo_value"; # Shell comments can also come after the code like this.
?>
# Shell-style comment tags like those used in Perl look like this.
# And the comment tag is only good for one line.
$foo = "foo_value"; # Shell comments can also come after the code like this.
?>
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.
CODE
<?
/* Place your comment here and then close the comment */
?>
/* Place your comment here and then close the comment */
?>
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.
CODE
<?
/* My comment can be as long as I want,
it can even use several lines.
Whenever I get done commenting,
I simply close the the comment. */
?>
/* My comment can be as long as I want,
it can even use several lines.
Whenever I get done commenting,
I simply close the the comment. */
?>
Additionally, the C-style comment can come before or after any code as long as the open and close tags are used properly.
CODE
<?
/* Let's describe the code below,
the code below is a variable definition. */
$foo = "foo_value"; /* The value of $foo is "foo_value" */
/* But we have a second variable */ $widget = "5"; /* The value of $widget is "5" */
?>
/* Let's describe the code below,
the code below is a variable definition. */
$foo = "foo_value"; /* The value of $foo is "foo_value" */
/* But we have a second variable */ $widget = "5"; /* The value of $widget is "5" */
?>
CODE
##########################################################
## ##
## Code Commenting Part Two - When To Comment ##
## ##
##########################################################
## ##
## Code Commenting Part Two - When To Comment ##
## ##
##########################################################
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:
CODE
###########################################################
## ##
## Code Commenting Tutorial Script In PHP. ##
## To be used by new programers to explain commenting ##
## Version 1.1 ##
## Non Copyrighted Material ##
## Witten By John Doe ##
## ##
###########################################################
## ##
## Code Commenting Tutorial Script In PHP. ##
## To be used by new programers to explain commenting ##
## Version 1.1 ##
## Non Copyrighted Material ##
## Witten By John Doe ##
## ##
###########################################################
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.
CODE
<?
// build_input_field() uses the arguments collected by the function call to create an HTML form input field.
function build_input_field($type,$name,$value,$size,$maxlength) {
$field = "<INPUT TYPE=\"$type\" NAME=\"$name\" VALUE=\"$value\" SIZE=\"$size\" MAXLENGTH=\"$maxlength\"><BR>\n";
return $field;
}
?>
// build_input_field() uses the arguments collected by the function call to create an HTML form input field.
function build_input_field($type,$name,$value,$size,$maxlength) {
$field = "<INPUT TYPE=\"$type\" NAME=\"$name\" VALUE=\"$value\" SIZE=\"$size\" MAXLENGTH=\"$maxlength\"><BR>\n";
return $field;
}
?>
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:
CODE
<?
// Next I'd like to write a function that will automatically build a HTML form based on information
// found in an SQL database table.
// First I need a master function that will controll smaller functions
function foo_master() {
function foo_secondary_1() {
if (condition) {
$x = 1;
return $x;
}
function foo_secondary_2() {
if (condition) {
$x = 2;
return $x;
}
}
}
?>
// Next I'd like to write a function that will automatically build a HTML form based on information
// found in an SQL database table.
// First I need a master function that will controll smaller functions
function foo_master() {
function foo_secondary_1() {
if (condition) {
$x = 1;
return $x;
}
function foo_secondary_2() {
if (condition) {
$x = 2;
return $x;
}
}
}
?>
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
Keep up the good work vujsa...
