Summary: this tutorial shows you how to use PHP comment to write great documentation for your source code.
PHP comment is a very important part of the code. PHP comment makes the code easier to read and maintain. PHP supports two types of comments:
- One-line comment
- Multiple-lines comment
PHP one-line comment
PHP one-line comment comes from C++ and Perl. PHP one-line comment is used to make a comment for just one line of code. It starts with pound ( #) or ( //) sign. The rest of text after the sign is ignored by PHP interpreter.
Let’s take a look at the following examples of using one-line PHP comment:
1 2 3 4 5 | <?php $rate = 100; $hours = 173; $payout = $hours * $rate; // payout calculation |
or using hash (#) sign:
1 2 3 | <?php $title = 'PHP comment'; # set default title |
PHP multiple lines comment
Multiple lines comment comes from C/C++. It starts with /* and ends with */. Whenever the comment needs to span on multiple lines, you use multiple lines comment.
The following example shows you how to use multiple lines comment:
1 2 3 4 5 6 | <?php /* * The following example demonstrates how to use * multiple-lines comment in PHP * */ $x = 20; |
Tips on writing PHP comment effectively
To write great documentation for your source code, you can use the following tips:
- Make the code speaks for itself without using supporting comments by using meaningful variables, functions or class names. The code itself is a great comment.
- Don’t write what code does but why you are writing this piece of code. Let’s the code explains what it does. However only you as a developer know why the code is doing that therefore you have to explain it in the comment.
- When writing a comment, make it as concise as possible.
- Use phpDocumentor to create fantastic documentation for your code.
In this tutorial, we have shown you various ways to comment your code and introduced you some tips on writing PHP comment effectively.