PHP Comments, Include/Include_once, Require/Require_once

Why use Comments?

• If you do not work on the source code for some time, it is easy to forget what the code does. Commenting the source code helps you remember what the code does.
• Commenting source code is also very important when multiple developers have to work on the same project. The changes made by one developer can be easily understood by other developers by simply reading the comments.
• As a best practice, you should have 3 lines of comments for every 10 lines of code.

PHP Comments

• Comments help us to understand the code
• Comments are explanations that we include in our source code. These comments are for human understanding.
• Single line comments start with double forward slashes // and they end on the same line.
• 
• Multiple line comments start with a forward slash followed by the asterisk /* and end with the asterisk followed by the forward slash */.
• 

The diagram below shows a PHP file with both multiple line and single line comments.

PHP Example

PHP Include & PHP Include_once

The “include” PHP statement is used to include other files into a PHP file.

It has two variations, include and include_once. include_once is ignored by the PHP interpreter if the file to be included has already been included.

The include statement has the following syntax

<?php
include 'file_name';
?>

The include_once statement has the following syntax

<?php
include_once 'file_name';
?>

HERE,

• “include/include_once” is the statement that includes the file
• “‘file_name'” is the name of the file to be included.

Example: Include / Include_once

Suppose you are developing a website that contains the same navigation menu across all the pages.

You can create a common header, then include it in every page using the include statement. Let us see how this can be done.

• We will create 2 files named
• header.php, index.php

Below is the code for header.php

<a href="index.php">Home</a>

<a href="aboutus.php">About us</a>

<a href="services.php">Services</a>

<a href="contactus.php">Contact Us</a>

index.php

<?php

include 'header.php';

?>

The header page above will output the navigation links.

PHP Require & PHP require_once

The require statement has two variations, require and require_once.

The require/require_once statement is used to include a file.

require_once is ignored if the required file has already been added by any of the four include statements.

It has the following syntax

<?php
require 'file_name';
?>

<?php
require_once 'file_name';
?>

HERE,

• “require/require_once” is the statement that includes the file
• “‘file_name'” is the name of the file to be included.

Example: Require

Suppose we are developing a database-powered application.

We can create a configuration file that we can include in all pages that connect to the database using the require statement. config.php

<?php

$config['host'] = 'localhost';

$config['db'] = 'my_database';

$config['uid'] = 'root';

$config['password'] = '';

?>

Let us now look at the sample code that requires the config file. Pages_model.php

<?php

require 'config.php'; //require the config file

//other code for connecting to the database

?>

PHP include vs require

The difference between include and require is shown below.

Generally, it is recommended to use the include statement so that when an error occurs, execution of the script continues to display the webmaster email address or the contact us page.

The require statement should be used if the entire script cannot run without the requested file.

The “include” and “require” statements can be used at any line in the source code where you want the code to appear.

PHP Documentation Comments (PHPDoc)

Beyond single and multi-line comments, PHP developers use PHPDoc block comments to document functions and classes. A PHPDoc block starts with /** and uses tags such as @param and @return that IDEs read to show hints and autocomplete.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number
 * @param int $b The second number
 * @return int The sum of the two numbers
 */
function add($a, $b) {
    return $a + $b;
}
?>

PHPDoc does not change how the code runs, but it makes the intent of each function clear and lets tools generate API documentation automatically. Adding it to shared files, such as the config and helper files above, keeps a growing codebase maintainable.

FAQs