Transwiki:PHP Programming/Commenting and Style

As you write more complex scripts, you'll see that you must make it clear to yourself and to others exactly what you're doing and why you're doing it. Comments and "good" naming can help you make clear and understandable scripts because:

• When writing a script takes longer than a week, by the time you're done, you won't remember what you did when you started, and you will most likely need to know.
• Any script that is commonly used will need rewriting sooner or later. Rewriting is much easier (and in many cases, made possible) when you write down what you did.
• If you want to show someone your scripts, they should be nice and neat.

The comments

Comments are pieces of code that the PHP parser skips. When the parser spots a comment, it simply keeps going until the end of the comment without doing anything. PHP offers both one line and multi-line comments.

One-Line Comments

One-line comments are comments that start where ever you start them and end at the end of the line. With PHP, you can use both // and # for your one-line comments (# is not commonly used). Those are used mainly to tell the reader what you're doing the next few lines. For example:

 //Print the variable $message
 echo $message;

It's important to understand that a one-line comment doesn't have to 'black out' the whole line, it starts where ever you start it. So it can also be used to tell the reader what a certain variable does:

 $message = ""; //This sets the variable $message to an empty string

The $message = ""; is executed, but the rest of the line is not.

One-line Comment Issues

• One-line comments end by either:

1. a newline (an actual newline, not the \n newline mark ) OR:
2. a closing PHP tag of the ?> variety

• If a one-line comment is closed by a closing PHP tag will not be commented. The following will thus print out "2":

// echo "1"; ?> echo "2";

Multi-Line Comments

This kind of comment can go over as many lines as you'd like, and can be used to state what a function or a class does, or just to contain comments too big for one line. To mark the beginning of a multiline comment, use /* and to end it, use */ . For example:

  /* This is a
  multiline comment
  And it will close
  When I tell it to.
  */

You can also use this style of comment to skip over part of a line. For example:

  $message = ""/*this would not be executed*/;

Although it is recommended that one does not use this coding style, as it can be confusing in some editors.

Multi-line Comment Issues

• An unfinished multi-line comment will result in an error, unless it is starting (not closing) within an already existing multi-line comment block (i.e., it is non-greedy but only operates first on a complete open and close set)
  • The following will result in an error:

     /* test */ */
    

  • The following will not result in an error:

     /* test /* */
    

• Thus, these multi-line comments cannot be nested (the first block up to "ending first comments" will be commented out, but the following */ will not have any opening /*for it). The following will therefore cause an error:

/*
Starting first comments
/*
Starting Nested comments
Ending nested comments
*/
Ending first comments
*/

• One can quickly toggle multiple blocks at a time by combining the styles (though this may not work show as such correctly in a text editor)

Original text with nothing commented out (thus printing "block one block two":

<?php
//*
print "block ";
print "one ";
// */
print "block ";
print "two";
?>

After taking out a / on the first line, the first block is commented out, printing only "block two":

<?php
/*
print "block ";
print "one ";
// */
print "block ";
print "two";
?>

Since the single line // overrides the multi-line /* .. */ two blocks of code can be switched at the same time back and forth into or out of comment mode.

Original text (printing out only "block one")

<?php
//*
print "block";
print "one";
/*/
print "block";
print "two";
// */
?>

After taking out a / on the first line, the first block is commented out and the second block is uncommented, printing out only "block two":

<?php
/*
print "block";
print "one";
/*/
print "block";
print "two";
// */
?>

• phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html PHPDocumentor uses multiline comments (albeit with the opening immediately followed by an additional asterisk "/**") and other standardized tags within the comment block to create its automatic documentation. See the website for additional instructions. For example:

<?php
/**
 * This is my new fancy code...
 * @author Dr. Who
 * @version 1.0
 */
?>

Issues with Either Single or Multi-line Comments

When using multi-line comments with the typical "/" as delimiters in a regular expression, it is possible there will be a conflict, as an asterisk at the end of the expression (along with the closing "/" delimiter) could create something that would be parsed as a closer of the comments, thus leaving the succeeding "*/" without an opener:

<?php
/*
$subject = "Hi Joe";
$matching = preg_match($subject, '/^Hi.*/');
*/

?>

To avoid the problem, one could:

• Use other regular expression delimiters--delimiters that may be less frequently encountered (and thus also in need of escaping) in most circumstances anyhow (e.g., "@" besides for email matching may be less frequent than "/")
• Use an "if" with an impossible conditional that can:

Avoid regular expression conflicts:

<?php

if (0) {
  $subject = "Hi Joe";
  $matching = preg_match($subject, '/^Hi.*/');
}

?>

and also avoid nesting problems:

<?php

if (0) {

  if (0) {
    print "Hi ";
  }

  print "Bob";
}

?>

One disadvantage of the "if" method, however, is that it will most likely not be recognized by text editors as far as code coloring (though this may be an advantage for debugging, if one wishes to see more clearly what is inside the commented out block while running tests on the code).

Naming

Naming your variables, functions and classes correctly is very important. If you define the following variables:

$var1 = "PHP";
$var2 = 15;

They won't say much to anyone. But if you do it like this:

$programming_language = "PHP";
$menu_items = 15;

It would be much clearer. But don't go too far. $programming_language, for example is not a good name. It's too long, and will take you a lot of time to type and can affect clarity. A better name may be $prog_language, because it's shorter but still understandable. Don't forget to use comments as well, to mark what every variable does.

$prog_language = "PHP";  //The programming language used to write this script
$menu_items = 15;        //The maximum number of items allowed in your personal menu

Magic numbers

When using numbers in a program it is important that they have a clear meaning. For instance it's better to define $menu_items early on instead of using 15 repeatedly without telling people what it stands for. The major exception to this is the number 1; often programmers have to add or subtract 1 from some other number to avoid off-by-one errors, so 1 can be used without definition.

When you define numbers early on in their usage it also makes it easier to adjust the values later. Again if we have 15 menu items and we refer to them ten times, it will be a lot easier to adjust the program when we add a 16th menu item; just correct the variable definition and you have updated the code in 10 places.

Spacing

PHP ignores extra spaces and lines. This means, that even though you could write code like this:

if ($var == 1) {echo "Good";} else {echo "Bad";}

It's better like this:

if ($var == 1) {
  echo "Good";
} else {
  echo "Bad";
}

Some programmers prefer this way of writing:

if ($var == 1)
{
  echo "Good";
}
else
{
  echo "Bad";
}

You should also use blank lines between different portions of your script. Instead of

$var = 1;
echo "Welcome!<br />";
echo "How are you today?<br />";
echo "The answer: ";

if ($var == 1) {
  echo "Good";
} else {
  echo "Bad";
}

You could write:

$var = 1;

echo "Welcome!<br />";
echo "How are you today?<br />";

echo "The answer: ";

if ($var == 1) {
  echo "Good";
} else {
  echo "Bad";
}

And the reader will understand that your script first declares a variable, then welcomes the user, and then checks the variable.

The directives

It's possible to define certain PHP compiling behaviors by some directives written in the command declare(). For example:

 declare(encoding = "UTF-8");