PHP 101
  • Home
  • Deploy
  • How-to
  • Tutorial
No Result
View All Result
PHP 101
  • Home
  • Deploy
  • How-to
  • Tutorial
No Result
View All Result
PHP 101
No Result
View All Result
Home How-to

How to Write PHP Comments (and best practices)

January 20, 2022
Reading Time: 3 mins read
PHP101.net - How to Write PHP Comments (and best practices)

PHP101.net - How to Write PHP Comments (and best practices)

Share on FacebookShare on Twitter

Do you feel good looking at PHP projects with thousands of classes, and functions without knowing what they do? Or even just a few lines of codes but you quickly forgot what the previous lines do? Well, I did. That’s why you should know how to write PHP comments, and – I mean, do it the right way.

TL;DR

You can quickly write PHP comments by three methods:

  • Use double forward slashes: //
    This method is only used for single-line comments.
  • Forward slash and asterisk – Block type: /* (open) and */ (close)
    This method can be used for both single-line and multiline comments.
  • Use hash sign: #
    Similar to forward slashes, this method can be used for single-line comments.

Quick PHP comments example:

// This is a single-line comment
echo "apple is red \n";

/* This is a multiline comment.
   We can continue our comment on the other lines.
   Remember to close it!
*/
echo "banana is yellow \n";

# This is another type of single-line comment
echo "orange is orange!";

And the comment won’t be outputted to the user:

apple is red
banana is yellow
orange is orange!

That’s all the basic tips you need for writing PHP comments.

Below are other tips to know for getting your PHP comments written properly, and following PHP coding standards.

What are PHP comments and why should we write comments?

Like any other programming language, PHP comment helps organize your PHP project code structure for better understanding and debugging purposes, and also adds explanation and clarification to the other PHP developers looking at your code.

For example, do you want your PHP codes (or somebody’s codes) to look like this?

$class = new someClass();
$here = $class->doThis()->doThat();
$there = $here->alsoDoThat($someVar);

Or should it be like this?

// Initialize the class
$class = new someClass();

// Get $class to doThis() and doThat()
$here = $class->doThis()->doThat();

// Then get $here to alsoDoThat() with $someVar
$there = $here->alsoDoThat($someVar);

Of course, these are just dummy codes, but imagine a project with thousand of lines of codes, functions, classes, it would be a real nightmare without any comments to tell the developer what is everything.

Having clear PHP comments is highly recommended, especially in your public GitHub projects, or company/team PHP projects which is a must.

Best practices to write PHP comments

Although PHP comments can be written the way you preferred, to follow PHP coding standards and make it developer friendly, there are several recommended guidelines when writing comments in PHP projects:

1. Use forward slashes // for single-line comments

Single-line comments should be used by forward slashes method:

// CORRECT: This is a single-line comment  

/** INCORRECT: This is a single-line comment but using asterisk method **/

2. Use forward slash + asterisk (block type) /* */ for multiline comments

Multiline comments should be used by slash + asterisk method:

/** 
 * CORRECT: This is a 
 * multiline comments
 * in block style
**/

// INCORRECT: This is a
// wrong way of using
// multiline comments.
// Sadly, I used it a lot in my projects :-)

3. Use block type /* */ for header comments

Header comments are the starting comments of a PHP file to clarify the content to the developer.

<?php

/** 
 * This is a PHP file for viewing PHP information
**/

phpinfo();

4. Use block type /* */ as DocBlock format to document PHP functions and classes

DocBlock is an adaptation of Javadoc for PHP programming, it allows external document generators and PHP IDEs to interpret variable types for providing code completion, type hinting, and debugging.

/**
* This is an example function
*
* @param string $text The text to do the magic
* @param int $number A number to make the magic even better
*
* @return string Return something
*/
public function magicFunction(string $text, int $number)
{
    // ...
}

5. Comments should be on their own line

// CORRECT: This is a comment on its own line
$apple = 'red';

$banana = 'yellow'; // INCORRECT: This comment should not be here

That’s all about general recommendations and tips for writing PHP comments in PHP development. This article could be updated later in case of new information, or when it should be revised.

Happy coding!

You might be interested in…

  • How to Add Elements to Array in PHP Easily

References

  • PHP comments on the official PHP Documentation website
  • PHPDoc and DocBlock on Wikipedia
Tags: how toPHP CommentWrite PHP Comments
Previous Post

How to Add Elements to Array in PHP Easily

Next Post

4 ways to increase PHP memory limit

Related Posts

PHP101.net - How to set timezone with PHP

How to set timezone with PHP easily (multiple methods)

March 9, 2023
PHP101.net - How to redirect to another page using PHP

How to redirect to another page using PHP

March 8, 2023

Table of Contents

    • TL;DR
    • What are PHP comments and why should we write comments?
    • Best practices to write PHP comments
    • 1. Use forward slashes // for single-line comments
    • 2. Use forward slash + asterisk (block type) /* */ for multiline comments
    • 3. Use block type /* */ for header comments
    • 4. Use block type /* */ as DocBlock format to document PHP functions and classes
    • 5. Comments should be on their own line
    • You might be interested in…
    • References
Next Post
PHP101.Net - How to increase PHP memory limit

4 ways to increase PHP memory limit

We deliver free and helpful resources for learning
and using PHP programming language.

About
Contact Us
Privacy Policy
Main Sections

Home
Deploy
How-to
Tutorial
You might be interested in...

How to install Composer on Linux

How to change Laragon PHP version on Windows

How to get user IP address using PHP

How to install PHP on Windows – Standalone method

How to install ImageMagick on Windows

© 2022 PHP101.Net - Helpful PHP Tutorials, How-to, Tips and Tricks for everyone.

No Result
View All Result
  • Home
  • Deploy
  • How-to
  • Tutorial

© 2022 PHP101.Net - Helpful PHP Tutorials, How-to, Tips and Tricks for everyone. | Privacy Policy

This website uses cookies. By continuing to use this website you are giving consent to cookies being used. Visit our Privacy and Cookie Policy.