How to Write PHP Comments (and best practices)

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.

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:

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

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.

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?

Or should it be like this?

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.

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:

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

Multiline comments should be used by slash + asterisk method:

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

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.

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!