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:
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.
// echo "1"; ?&gt; 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.
Starting first comments
Starting Nested comments
Ending nested comments
Ending first comments
Original text with nothing commented out (thus printing "block one block two":
&lt;?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":
&lt;?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")
&lt;?php
print "block";
print "one";
print "block";
print "two";
?&gt;
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":
&lt;?php
print "block";
print "one";
print "block";
print "two";
?&gt;
&lt;?php
 * This is my new fancy code...
 * @author Dr. Who
 * @version 1.0
?&gt;
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:
&lt;?php
$subject = "Hi Joe";
$matching = preg_match($subject, '/^Hi.*/');
To avoid the problem, one could:
Avoid regular expression conflicts:
&lt;?php
if (0) {
 $subject = "Hi Joe";
 $matching = preg_match($subject, '/^Hi.*/');
and also avoid nesting problems:
&lt;?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).
Styles.
The PHP coding styles are defined in the .
Naming.
Naming your variables, functions and classes correctly is very important to understand the program. By convention, it should be done in and without any abbreviation.
If you define the following variables:
$var1 = "PHP";
$var2 = 15;
They won't say much to anyone. But if you do it like this:
$programmingLanguage = "PHP";
$menuItems = 15;
It would be much clearer.
But don't go too far. "$programmingLanguage", 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 "$progLanguage", because it's shorter but still understandable. A good naming should avoid to write a comment to mark what every variable does.
For instance, these comments are encumbering the script and should be removed:
// The programming language used to write this script
$progLanguage = "PHP";
// The maximum number of items allowed in your personal menu
$maxMenuItems = 15;
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:
It's better like this, which is the PSR-2 form:
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!&amp;lt;br /&amp;gt;";
echo "How are you today?&amp;lt;br /&amp;gt;";
echo "The answer: ";
if ($var == 1) {
 echo "Good";
} else {
 echo "Bad";
You could write:
$var = 1;
echo "Welcome!&amp;lt;br /&amp;gt;";
echo "How are you today?&amp;lt;br /&amp;gt;";
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 codice_1. For example:
 declare(encoding = "UTF-8");