PHP Dev Hack: Shell Style Comments

If you’ve done any PHP coding, you’ve learned that PHP supports 3 styles of comments.

The first is a single line comment use two forward slashes`//` which comments everything until the end of the line. This is a C++ style comment. A second single line comment style are “shell style”, which use the pound sign `#` to comment out everything until the end of the line. Then there’s the C-style comments, which are multi-line comment characters where /* starts the comment, and `*/` ends the comment, and can be used across multiiple lines. Of these 3 styles, the shell comments are the least used.

The Dev Hack

Most PHP don’t use the shell style comments. In fact, they’re usually discouraged, and usually prohibited according to most Coding Style Guides. Because of this, that’s why you should use them. You use them when you are refactoring, and you’re pretty sure that you want to delete some lines of code. Shell style comments let you disable a line of code, but still keep the code readable. If you just delete the lines, you’ll have to rely on your version control to identify the deleted lines. That’s not their only use. They can also be used for debugging comments. They stand out from the legitimate comments that explain your code.

These are effective, becuase if you see these shell style comments in your file diffs when you’re committing your code, you know that you have  some clean up to do. You can either delete the lines, or choose to change to one of the other comment styles. It’s also a good opportunity to reword the comments.

If you decide to use this tactic, consider adding a pre-commit check to prevent shell style comments from being committed.