Comments

In this lesson, learn how to write comments in your PHP script.

What are comments?

Similar to HTML, PHP supports comments. Comments are non-executable lines of code ignored by the PHP interpreter and used to provide readable notes to the code for better understanding. It's considered incredibly helpful to provide explanations or annotations to the code you've written. They are like notes in a notebook or margin notes in a book that helps you remember what you were thinking or what certain parts of the code are for.

Comments in code can be used to describe what a specific section of code is doing, to provide reminders or to-do items, to temporarily disable parts of the code, or for any other purpose that helps you understand the code better or make it easier to maintain.

By using comments, you can make your code more readable and understandable, both for yourself and for others who may need to work with your code in the future. This is especially important for large or complex codebases, where understanding the purpose and organization of the code is critical.

Writing Comments

In PHP, there are two types of comments: single-line comments and multi-line comments.

Single-line comment

A single-line comment starts with two forward slashes (//) and continues until the end of the line. For example:

<?php
 
// This is a single-line comment

Alternative syntax for single-line comments

There's an alternative syntax for writing single-line comments, which is to use the hash symbol (#). It isn't as popular as using two forward slashes, but you may find it out in the wild occasionally. For example:

There really isn't a difference between the two options. Both of these options are treated as single-line comments and are ignored by the PHP interpreter.

<?php
 
# This is a single-line comment

Multi-line comment

A multi-line comment starts with /* and ends with */. Everything between these two markers is considered part of the comment and ignored by the PHP interpreter. For example:

<?php
 
/*
This is a
multi-line comment
*/

When to write comments

A key indication of a proficient PHP developer lies in the comments they write: their presence and, sometimes, their meaningful absence. Good comments enable us to maintain the code effectively, revisit it after a period of time, and utilize it more efficiently.

It's a good idea to leave comments for:

The big picture of the code: what it's supposed to do as a whole.
How to use the functions you write.
Clever fixes or tricky parts that aren't easy to understand just by looking at the code.

Try not to leave comments that:

Only explain what the code is doing step by step.
If the code is simple and clear enough to understand on its own, it's best not to add extra comments.

Key takeaways

Multi-line comments are typically used when you need to provide a more detailed explanation or annotation.
Single-line comments are used for shorter explanations or temporarily disable a code line.
Only some things need to be commented. Only use them to add clarity for other developers or yourself when you revisit a codebase.