Having the ability to put developer comments into your code that don't get rendered out of the script (and onto your website view) makes up a critical skill for every PHP developer. Having comments allows other developers to share knowledge outside of what the code appears to do, with others. If you're working in a team, or solving a complex solution and think, this code in six months' time might not make sense straight away. Having comments would help clear up any preconceptions about what the code is meant to do. Let's explore the different styles of PHP comments, including how PHPDoc can be extremely useful for type hinting.
PHP comment style
Nearly every programming language available allows developers the ability to add comments to their code, and PHP is no exception to this rule. With PHP there are numerous comment styles available to use within your code. PHP supports 'C', 'C++', and 'Unix-based' comment styles.
C-based comments in PHP
Within PHP the first style of comment is the C-based comment which uses slashes and asterisks to determine the block comment. This is also known as a multi-line comment as it can extend over multiple lines within your script.
/*
This is a C-style comment and will not display to the user
*/C++ style comments in PHP
Similar to C-style comments, C++ comments are known as one-liner or single-line comments and use double slashes "//" to mark the start of the comment.
// This is a C++ style comment and will not display to the userUnix style comments in PHP
Similar to C++ style comments, Unix-based style comments are single-ling comments, that use a hash '#' symbol to determine the start of the comment. You'll see these styles of comments in a bash script and within Unix-based applications like a system's cron tab.
# This is a Unix-style comment and will not display to the userThere is no right or wrong way to use comments within your code, it normally comes down to personal preference however there are some best practices when it comes to comments in PHP. Generally, multi-line comments are used to describe a function's working also known as PHPDoc, where line comments are typically used within the function itself to describe how single-line aspects of the code work.
PHP comment nesting and common mistakes
It's easy for PHP comments to get mismatched within themselves. Take a look at the below example, because the comment is contained in the string, the comment will actually get rendered to the user, because PHP doesn't treat it as a comment, and instead thinks it is a string.
echo 'Test /* this will get rendered */';Another common mistake is nesting comments within comments. the below code will trigger an error "Parse error: syntax error, unexpected token "*", expecting end of file" because PHP is expecting a closing comment after the word "Test" but instead another comment is opened.
/* Test /* this will get rendered */ */Mixmatching comments therefore should be avoided. If opening a particular style of PHP comments, you should stick with that style until it's closed again to avoid PHP errors or unintentional comments being displayed to the user.
# This is /* confusing for // other */ devsBe sure to close multi-line comments to avoid PHP triggering a parse error. Take the below example, here because we haven't closed the multi-line comment, it broke PHP and triggered "Parse error: Unterminated comment starting".
/* this is incorrectWhat is PHPDoc?
PHPDoc is a type of documentation comment and the term used to describe how functions and classes work using native-type hinting. They describe what parameters are (using @param) and their type including what functions may return (using @return) or the type of errors that could occur (using @exception). Static analytics tools use this information to help with bug discovery as will your PHP IDE such as PHPStorm. If you browse open-source PHP software you'll quickly see PHPDoc used a lot. PHPDoc uses the multi-line comment structure with an asterisk at every new line. It also uses a double asterisk at the start of the block.
PHP developers also use PHPDoc attributes to mark other aspects of the code base where deemed necessary. Those include;
- @todo - to inform others that there are still things to be done with the given code
- @author - common in open-source software to add the author of the codebase
- @version - used to informally mark the current PHP software version
- @since - to inform developers when a new bit of code appears and what version that was
Take this example, here our PHPDoc block explains that our function 'foo' requires one parameter a boolean, and returns a string. Without reading the code, we can quickly start to work out what the function does just by reading the DocBlock. It's worth noting that a single-line comment ('#' or '//') isn't classed as PHPDoc. Using PHPDoc is a great way to keep your code well-documented, aid in code completion, and find ambiguities in your code, especially if your PHPDoc is different from what the function is actually doing.
/**
* @param bool $param
* @return string
*/
function foo(bool $param) {
return 'test';
}Conclusion
Getting into the habit of commenting on your code as you go is a great way to develop maintainable and easier-to-read applications. If a time you think, maybe this code is becoming a little complex, you should try to document what the code does with PHP comments, to ensure next time around you can jump in quicker, without having to spend time re-remembering all of the function's code.
- Use a hash '#', double slash '//' or slash followed by an asterisk '/*' to create a comment in PHP
- Use PHPDoc for your classes and functions within PHP
- PHPDoc should always start with a slash and asterisk '/*'