Welcome to PHPBash. In this PHP Tutorial, we will learn about Basics PHP Comments. In our Previous Tutorial, we learn about basics of PHP syntax as well fundamentals of comments. Basically, PHP Comments are part of PHP Program which is not executed by PHP parser while Executing PHP Program. PHP Comments can be Single line or multiline.
PHP Comment Style Guide and PHP Coding Standards
In this, PHP tutorial covers all the topics of Basics of PHP Comments styles and Coding Standard like
1. What are Comments in PHP Programming Language?
2. Need of PHP Comments
3. Types of PHP Comments
4. PHP Comment Styling
5. PHP Comments Standards with Best Practices
6.PHP Comments Example with Valid and Invalid Examples
Now let's start this tutorial with understanding What are Comments in PHP Programming Language?
What are Comments in PHP Programming Language?
In PHP, Comments are part of PHP program or script which is not Interpreted by PHP Parser while Executing PHP Script or PHP program. In any programming language, Comments are part of code which never Executed language compiler or Interpreter.
Comments describe the code functionality and how to use it. Comments are also useful for providing more details about particular statement or function or any other statement.
Need of PHP Comments
1. The main purpose of PHP Comments are to describe the PHP program.
2. It helps of Comments, Other people can understand code.
3. The readability of Script or program can be improved with Comments.
4. The particular Logic or part of code can be described with help of comments.
5. Information other than PHP code, can be included within file like License Information,Author details, Version of file etc. For Example:
 |
| PHP Comments Example |
Types of PHP Comments
Like other programming language PHP also supports two types of Comments- Single Line Comments and Multi-line Comments. Single Line Comments are useful for shot description where as multi-Line Comments are useful for long description.
PHP Single Line Comments
For creating Single Line Comments in PHP Code, you need to use // or # before the comment line. Consider following example,
<?php
# Single Line Comment 1
# Single Line Comment 2
# Single Line Comment 3
// Another way to use Single Line Comments in PHP
echo "Example of Single Line Comment.";
?>
PHP Comments are also useful for skipping certain part of code. For Example:
<?php
//You can also use comments to leave out parts of a code line
$ctr = 85 /* - 52 */ * 54;
echo "The Counter value".$ctr;
?>
PHP Multi-Line Comments
For creating Multi-line Comments in PHP Code, you need to use /* ... */. Consider following example,
<?php
/*
This is Multiline Comment Example
Where more than one lines are available
in Comments.
*/
echo "Example of Multi-Line Comment.";
?>
PHP Comment Styling Guide
The Following Example demonstrate various Styles of PHP Comments used in PHP Program for describing details.
<?php
//=================================================================
// COMMENTS IN LARGER FONT
//=================================================================
//-----------------------------------------------------
// Comments in Smaller font
//-----------------------------------------------------
/* Starting of Program */
# Flag 1
# Flag 2
# Flag 3
/*
* This is Multi line Comment
* with more a detailed explanation
*
*/
// Single Line Comment 1
/* Ending of Program */
?>
 |
| PHP Comments Styles Example |
PHP Comments Standards with Best Practices
1. Single-line comments MUST use two forward slashes
<?php
// Comment 1
echo "Single-line comments MUST use two forward slashes";
?>
2. Multi-line comments MUST use the block format
<?php
/**
* Comment 1
*/
echo "Multi-line comments MUST use the block format";
?>
3. Header comments SHOULD use the block format
<?php
/**
* Name of code section
*/
echo "Header comments SHOULD use the block format";
?>
4. Comments MUST be on their own line
<?php
//Name of code section
echo "Comments MUST be on their own line";
?>
5. Blocks of code SHOULD be explained or summarized
<?php
//The details of logic should be given
echo "Blocks of code SHOULD be explained or summarized";
?>
7. Ambiguous numbers MUST be clarified
8. External variables MUST be clarified
<?php
//$conn is Connection variable for database
$conn=mysqli_connect("localhost","test","test","test_db");
?>
PHP Comments Example with Valid and Invalid Examples
The following Example Demonstrates the valid and invalid examples of various comments in PHP.
1. Single-line Comments
Single-line comments MUST use two forward slashes.
Invalid
<?php
/* This is a comment */
// End of File
?>
Reason: Incorrect because it uses /* and */ for a single-line comment.
Valid
<?php
// This is a comment
// EOF
?>
2. Multi-line Comments
Multi-line comments MUST use the block format.
Invalid
<?php
// This is a
// multi-line
// comment
// EOF
?>
Reason: Incorrect because it uses // for a multi-line comment.
Valid
<?php
/**
* This is a
* multi-line
* comment
*/
// EOF
?>
3. Divider Comments
Divider comments SHOULD use the block format with 75 asterisks in between.
Invalid
<?php
/**#######################################################################*/
// EOF
?>
Reason: Incorrect because it uses # instead of *.
Invalid
<?php
/******************/
// EOF
?>
Reason: Incorrect because it uses 15 instead of 75 *.
Valid
<?php
/**
* Beginning + Middle + End
* 3 spaces + 75 spaces + 2 spaces = 80 character line limit
*/
/******************************************************************************/
// EOF
?>
4. Comments
Comment MUST be on their own line.
Invalid
<?php
test_function(); // Calling test function
// EOF
?>
Reason: Incorrect because // Prints welcome message is not on its own line.
Valid
<?php
// Calling test function
test_function();
// EOF
?>
5. Blocks of Code
Blocks of code SHOULD be explained or summarized.
Invalid
<?php
if ($expression2)
{
// Comment 1
} else if($expression3){
// Comment 2
}
if ($expression4) {
// Comment 3
} elseif ($expression5) {
// Comment 4
} else {
// Comment 5
}
// Comment 6
// EOF
?>
Reason: Allowed, but block of code should be explained or summarized.
Valid
<?php
/**
* Line 1 description
* Line 2 description
* Line 3 description
*/
if ($expression2)
{
// Comment 1
} else if($expression3){
// Comment 2
}
if ($expression4) {
// Comment 3
} elseif ($expression5) {
// Comment 4
} else {
// Comment 5
}
// Comment 6
// EOF
?>
I would acknowledge you sharing your individual experiences about "PHP Comment Style Guide and Coding Standards". If you have any doubt/query related to PHP or Web Technologies, Please let me know in Comment Section.
I will certainly take care that, I should give reply for every single comment on my blog posts. So, let’s fire the discussion up! See you in the comments section below..
Sharing is caring ❤️
Thank you for Visiting PHPBash. Keep Visiting for more Interesting concepts of Php language and web technologies from basics to advanced. As well we will also share some ready-to-use, useful code snippets for beginners to kick start their web development project.
Comments
Post a Comment
Thank you so much.