Programming:PHP/comments

From Wikibooks, the open-content textbooks collection

Return to PHP.

Contents 1 Introduction 2 Comments 2.1 One-Line Comments 2.2 Multi-Line Comments 3 Naming 3.1 Magic numbers 4 Spacing

[edit] Introduction

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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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

[edit] 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.

[edit] 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.