PHP Comments

Should you document your code?

PHP has a few different options when it comes to comments. Frequently, it’s based on preference on which comment style you use, but other times it makes sense to use one over the other.

PHP Comments allow you to write brief or detailed descriptions explaining what the code that you wrote actually does. You, or someone else, will come back to your code years from now and will try to decipher what it actually means. You should always strive to write code that’s self-explanatory, but every once in while, you may want to specify a little additional detail.

The first type of comment starts with //. They’re single line comments, meaning that whatever you write on that one particular line will be ignored by PHP.

 

<?php
// This is a comment inside PHP
This will throw an error
?>

 

Another single line comment starts with #.

 

<?php
# This is a single line comment
# This is another single line comment
# $x should be named $title
$x = "Mr";
?>

 

The last type of comment is the /** */. It starts with /** and ends with */. This can be used as a single line or multi-line comment. Any characters placed between /** and */ will be commented out regardless of how many lines the characters span.

 

<?php
/** Comment */
/**
  Multi-line comment
  This is also part of the comment
  $x = "Hey"; <- Still a comment
*/
?>

 

Comments don’t have to be on separate lines since anything after the comment symbol is marked as a comment.

 

<?php
$x = "Mr"; // $x should be named $title
$y = "Dino"; # $y should be named $first_name
$z = "Cajic"; /** $z should be named $last_name */
?>

 

If you look at the last comment, it needs to have the closing symbol */ or it will continue to comment out anything afterwards. Sometimes when you’re testing, it makes a lot more sense to use the multi-line comment to take out certain sections of the code.

It doesn’t matter if the code below makes sense or not to you yet, just know that the for loop is commented out and will not be interpreted by PHP.

 

<?php
$x = "Frank";/**
for ( $i = 0; $i < 10; $i++ ) {
  echo $x . "_" . $i;
}
*/?>

 

You can also use the multi-line comment to comment out specific sections of the code. The code below will comment out the “_” . $i.

 

<?php
$x = "Frank";for ( $i = 0; $i < 10; $i++ ) {
  echo $x . /** "_" . $i*/;
}?>

 

By convention, when you do a multi-line comment, you will add an asterisk for each new line.

 

/**
 * This is a multi-line comment. 
 * 
 * Author: Dino Cajic
 * Copyright Year: 2020 
 * 
 * No. This code is not copyrighted.
 */

 

Create a new file and name it comments.php. You’ll be able to visit it inside your browser by going to http://localhost/comments.php. Copy and paste the code below and open up the page in your browser. See what’s displayed on the screen and see what’s displayed when you view the source. You’ll realize that comments are nowhere to be found. They’re just for you to see in your code.

 

 

Specific comment conventions can also be used to generate documentation for your PHP code with the assistance of phpDocumentor. I suggest that you get yourself familiarized with phpDoc as well; you’ll probably see it used throughout your classes in object oriented PHP. JetBrains PHP Storm comes preloaded with phpDoc.

 

PHP Tutorial Series

Continue your learning with these articles

PHP Basic Syntax

Where to Begin?

PHP – P1: BASIC SYNTAX

PHP is leaps and bounds above where it started. It’s a modern programming language that has Object Oriented capabilities. It’s the backbone of popular frameworks like Laravel. To get us started, let’s learn the syntax.

PHP Comments

Should you document your code?

PHP – P2: Comments

PHP has a few different options when it comes to comments. Frequently, it’s based on preference on which comment style you use, but other times it makes sense to use one over the other.

PHP Variables

CAN YOU EVEN STORE DATA?

PHP – P3: VARIABLES INTRO

Variables are just storage containers. You can store any data type that you would like inside of them.

Leave a Reply